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

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, 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, 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, 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 (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.

2. Publish the API – The server implementation (often started from 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 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 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:

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, 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:

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, 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:

# 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, 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.

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	High‑level overview of the protocol, resources, and roadmap	Repository root
lib/core/src/lib.ts	TypeSpec‑based definition of the Common Grants model and validation utilities	lib/core/src/lib.ts
lib/cli/src/index.ts	CLI driver for spec validation, OpenAPI generation, and compliance checks	lib/cli/src/index.ts
lib/ts-sdk/src/client/opportunities.ts	Typed client methods for retrieving opportunities, applications, and awards	lib/ts-sdk/src/client/opportunities.ts
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
templates/express-js/README.md	Boilerplate Express.js server implementing a fully compliant Common Grants API	templates/express-js/README.md
website/README.md	Public website source, including documentation and interactive playground	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), CLI tooling (lib/cli/src/index.ts), language SDKs (lib/ts-sdk/src/client/opportunities.ts), and server templates (templates/express-js/README.md).
• Custom fields are supported through extension helpers (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) 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) can parse responses from any compliant server. Additionally, the @common-grants/cli tool (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, 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) 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. 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 include built-in middleware that ensures responses conform to the expected schemas.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}