# What Is the CommonGrants Protocol? A Complete Guide to the Open-Source Grant Data Standard

> Discover the CommonGrants protocol, an open-source standard for seamless grant data exchange between funders, applicants, and platforms. Learn about its purpose with this complete guide.

- Repository: [U.S. Department of Health & Human Services/simpler-grants-protocol](https://github.com/hhs/simpler-grants-protocol)
- Tags: getting-started
- Published: 2026-03-03

---

**The CommonGrants protocol is an open-source, language-agnostic specification that defines a standard data model and API contract for grant-related information, enabling interoperable exchange of grant data across funders, applicants, and platforms without custom integrations.**

The CommonGrants protocol is an open-source initiative maintained in the `hhs/simpler-grants-protocol` repository that establishes a universal "common language" for grant data. By standardizing how opportunities, applications, and awards are structured and exchanged, the protocol eliminates data silos and reduces the integration burden for developers building grant management systems.

## Core Architecture of the CommonGrants Protocol

The protocol is organized into five distinct layers that work together to provide a complete development ecosystem. Each layer is implemented as a separate package within the monorepo structure.

### Specification Layer

At the foundation lies the **TypeSpec** definition that formally describes the JSON schema, endpoints, and validation rules. This machine-readable specification ensures that any implementation conforms to the same data shapes. The core definitions reside in [`lib/core/src/lib.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/core/src/lib.ts), where the canonical models for opportunities, applications, and awards are declared.

### CLI Tooling

The `@common-grants/cli` package provides command-line utilities for developers to validate their API specifications against the protocol. Implemented in [`lib/cli/src/index.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/cli/src/index.ts), the CLI can check TypeSpec definitions for compliance, generate OpenAPI documentation, and verify that server responses match the expected schemas.

### SDKs and Client Libraries

Language-specific SDKs abstract the HTTP layer and provide typed client methods. The TypeScript SDK, located in [`lib/ts-sdk/src/client/opportunities.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/ts-sdk/src/client/opportunities.ts), exports methods like `list()` that return fully-typed objects matching the CommonGrants model. A Python SDK follows a similar structure in `lib/python-sdk/`, enabling polyglot development teams to interact with compliant APIs using idiomatic patterns.

### Server Templates

To accelerate adoption, the protocol provides boilerplate server implementations in [`templates/express-js/README.md`](https://github.com/hhs/simpler-grants-protocol/blob/main/templates/express-js/README.md) (Node.js/Express) and similar directories for FastAPI (Python) and Go. These templates expose a fully compliant Common Grants API out of the box, allowing funders to stand up a standards-compliant backend by configuring environment variables rather than writing integration logic.

## How the CommonGrants Protocol Works in Practice

The protocol follows a four-phase workflow that standardizes how grant data moves from definition to consumption.

1. **Define the API** – Funders use TypeSpec to describe their grant data model, including custom fields specific to their program. The `@common-grants/cli` validates these definitions against the canonical model in [`lib/core/src/lib.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/core/src/lib.ts).

2. **Publish the API** – The server implementation (often started from [`templates/express-js/README.md`](https://github.com/hhs/simpler-grants-protocol/blob/main/templates/express-js/README.md)) generates OpenAPI documentation automatically and serves JSON responses that strictly conform to the validated TypeSpec.

3. **Consume the API** – Client applications import the appropriate SDK (TypeScript from [`lib/ts-sdk/src/client/opportunities.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/ts-sdk/src/client/opportunities.ts) or Python equivalent) and call typed methods. The SDK handles request construction and returns objects that match the CommonGrants protocol schema exactly.

4. **Extend Safely** – The protocol supports **custom fields** that are version-controlled and discoverable. Funders can add domain-specific metadata without breaking compatibility with standard SDK methods, as extension helpers in [`lib/ts-sdk/src/extensions/get-custom-field-value.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/ts-sdk/src/extensions/get-custom-field-value.ts) provide safe access to these fields.

## Implementation Examples

The following code snippets demonstrate how developers interact with the CommonGrants protocol using the official SDKs and CLI tools.

### Listing Opportunities with the TypeScript SDK

This example shows how to initialize the client and retrieve paginated opportunity listings from a compliant API endpoint:

```typescript
import { CommonGrantsClient } from "@common-grants/sdk";

async function demo() {
  // Initialise client – base URL points at a Common Grants‑compliant server
  const client = new CommonGrantsClient({ baseUrl: "https://api.example.org" });

  // Fetch the first page of opportunities, sorted by startDate
  const response = await client.opportunities.list({
    page: 1,
    pageSize: 20,
    sort: [{ field: "startDate", direction: "desc" }],
  });

  // Typed result – each entry follows the Common Grants model
  response.data.forEach((opp) => {
    console.log(`${opp.id}: ${opp.title} (deadline ${opp.applicationDeadline})`);
  });
}

demo();

```

The client implementation lives in [`lib/ts-sdk/src/client/opportunities.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/ts-sdk/src/client/opportunities.ts), where the `list()` method constructs the HTTP request and parses the response into typed objects matching the canonical model.

### Accessing Custom Fields

The protocol allows funders to define custom metadata while maintaining type safety. Use the extension helper to retrieve these values:

```typescript
import { CommonGrantsClient } from "@common-grants/sdk";

const client = new CommonGrantsClient({ baseUrl: "https://api.example.org" });

// Retrieve a specific opportunity and its custom fields
const opp = await client.opportunities.get("opp-123");

// Custom field value is accessed through the extension helper
import { getCustomFieldValue } from "@common-grants/sdk/extensions";

const region = getCustomFieldValue(opp, "region");
console.log(`Opportunity region: ${region}`);

```

The `getCustomFieldValue` utility is implemented in [`lib/ts-sdk/src/extensions/get-custom-field-value.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/ts-sdk/src/extensions/get-custom-field-value.ts), providing a version-safe mechanism to access extended data without breaking standard SDK contracts.

### Validating Specifications with the CLI

Before deploying a server, validate that your TypeSpec definition conforms to the CommonGrants protocol:

```bash

# From a repository that contains a .tsp file defining the API

npx @common-grants/cli validate ./api.tsp

```

If the specification conforms to the canonical model defined in [`lib/core/src/lib.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/core/src/lib.ts), the CLI prints a success message; otherwise, it displays detailed validation errors indicating which constraints failed. The CLI entry point is located in [`lib/cli/src/index.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/cli/src/index.ts).

## Key Files and Their Roles

Understanding the repository structure helps developers navigate the protocol implementation. The following table maps critical files to their functions within the `hhs/simpler-grants-protocol` codebase:

| File | Role | Location |
|------|------|----------|
| [`README.md`](https://github.com/hhs/simpler-grants-protocol/blob/main/README.md) | High‑level overview of the protocol, resources, and roadmap | Repository root |
| [`lib/core/src/lib.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/core/src/lib.ts) | TypeSpec‑based definition of the Common Grants model and validation utilities | [`lib/core/src/lib.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/core/src/lib.ts) |
| [`lib/cli/src/index.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/cli/src/index.ts) | CLI driver for spec validation, OpenAPI generation, and compliance checks | [`lib/cli/src/index.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/cli/src/index.ts) |
| [`lib/ts-sdk/src/client/opportunities.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/ts-sdk/src/client/opportunities.ts) | Typed client methods for retrieving opportunities, applications, and awards | [`lib/ts-sdk/src/client/opportunities.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/ts-sdk/src/client/opportunities.ts) |
| [`lib/ts-sdk/src/extensions/get-custom-field-value.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/ts-sdk/src/extensions/get-custom-field-value.ts) | Helper for extracting version‑safe custom‑field values from SDK objects | [`lib/ts-sdk/src/extensions/get-custom-field-value.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/ts-sdk/src/extensions/get-custom-field-value.ts) |
| [`templates/express-js/README.md`](https://github.com/hhs/simpler-grants-protocol/blob/main/templates/express-js/README.md) | Boilerplate Express.js server implementing a fully compliant Common Grants API | [`templates/express-js/README.md`](https://github.com/hhs/simpler-grants-protocol/blob/main/templates/express-js/README.md) |
| [`website/README.md`](https://github.com/hhs/simpler-grants-protocol/blob/main/website/README.md) | Public website source, including documentation and interactive playground | [`website/README.md`](https://github.com/hhs/simpler-grants-protocol/blob/main/website/README.md) |

These files collectively demonstrate how the protocol’s **specification**, **tooling**, **SDKs**, and **templates** cooperate to deliver a universal, version‑controlled API for grant data.

## Summary

- The **CommonGrants protocol** is an open‑source specification that standardizes grant data models and API contracts across the funding ecosystem.
- It eliminates integration silos by providing a **single canonical language** for describing opportunities, applications, and awards.
- The protocol architecture includes a **TypeSpec core** ([`lib/core/src/lib.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/core/src/lib.ts)), **CLI tooling** ([`lib/cli/src/index.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/cli/src/index.ts)), **language SDKs** ([`lib/ts-sdk/src/client/opportunities.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/ts-sdk/src/client/opportunities.ts)), and **server templates** ([`templates/express-js/README.md`](https://github.com/hhs/simpler-grants-protocol/blob/main/templates/express-js/README.md)).
- **Custom fields** are supported through extension helpers ([`lib/ts-sdk/src/extensions/get-custom-field-value.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/ts-sdk/src/extensions/get-custom-field-value.ts)) that maintain backward compatibility.
- Developers can validate specifications using the `@common-grants/cli` before deployment to ensure compliance.

## Frequently Asked Questions

### What is the CommonGrants protocol used for?

The CommonGrants protocol standardizes how grant opportunities, applications, and awards are structured and exchanged across different software platforms. It enables funders to publish grant data in a consistent format that applicants and downstream services can consume without building custom integrations for each source. According to the `hhs/simpler-grants-protocol` source code, the protocol serves as a "common language" that removes data silos and reduces duplication across the grant ecosystem.

### How does the CommonGrants protocol ensure interoperability?

Interoperability is achieved through a **canonical data model** defined in TypeSpec ([`lib/core/src/lib.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/core/src/lib.ts)) that all implementations must follow. The protocol mandates specific JSON schemas for resources like opportunities and applications, ensuring that any client using the official SDKs ([`lib/ts-sdk/src/client/opportunities.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/ts-sdk/src/client/opportunities.ts)) can parse responses from any compliant server. Additionally, the `@common-grants/cli` tool ([`lib/cli/src/index.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/cli/src/index.ts)) validates that implementations conform to the specification, catching deviations before they reach production.

### What programming languages are supported by the CommonGrants SDKs?

The protocol currently provides official SDKs for **TypeScript** and **Python**. The TypeScript SDK, located in [`lib/ts-sdk/src/client/opportunities.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/ts-sdk/src/client/opportunities.ts), offers fully typed client methods for listing opportunities and retrieving application data. A Python SDK follows a similar structure in `lib/python-sdk/`. Both SDKs handle request building, response parsing, and provide extension helpers (such as [`lib/ts-sdk/src/extensions/get-custom-field-value.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/ts-sdk/src/extensions/get-custom-field-value.ts)) for accessing custom fields in a type-safe manner.

### How can I validate my API implementation against the CommonGrants protocol?

Developers can validate their implementations using the **`@common-grants/cli`** package. After defining your API in TypeSpec, run `npx @common-grants/cli validate ./api.tsp` to check compliance against the canonical model defined in [`lib/core/src/lib.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/core/src/lib.ts). The CLI outputs detailed error messages if your specification deviates from the protocol, allowing you to correct issues before deployment. For runtime validation, the server templates in [`templates/express-js/README.md`](https://github.com/hhs/simpler-grants-protocol/blob/main/templates/express-js/README.md) include built-in middleware that ensures responses conform to the expected schemas.