CommonGrants vs Simpler Grants Protocol: Understanding the Architecture

CommonGrants is the open API specification for grant data, while the Simpler Grants Protocol is the complete ecosystem—including SDKs, CLI tools, templates, and governance—that packages and delivers that specification.

The relationship between these two components is often a source of confusion for developers exploring the HHS Simpler Grants repository. While the terms are sometimes used interchangeably in casual conversation, they represent distinct architectural layers within the same codebase. Understanding the difference between CommonGrants and the Simpler Grants Protocol is essential for choosing the right integration path for your grant management system.

What Is CommonGrants?

CommonGrants is a stand-alone open standard that defines the data models, API endpoints, and validation rules for exchanging information about grant opportunities, applications, and awards. It is expressed in TypeSpec and compiled to OpenAPI specifications and JSON Schema.

The canonical definition lives in website/src/specs/main.tsp, which imports the core library to expose the base API:

// website/src/specs/main.tsp
import "@common-grants/core"; // pulls in the base spec

@route("/common-grants/opportunities")
opportunity get(id: Types.uuid): OpportunityBase;

As implemented in the source, CommonGrants provides the contract that any compliant API must fulfill. It does not provide the tooling to build or validate that API—it merely defines what the API should look like.

What Is the Simpler Grants Protocol?

The Simpler Grants Protocol is the umbrella initiative that bundles the CommonGrants specification together with the website, SDKs, CLI, templates, governance process, and version-management tooling. According to the repository's lib/README.md, it is the collection of "independently versioned packages that support the protocol."

The repository layout under lib/ contains the implementation artifacts:

• Node and Python packages for client libraries
• website/ for documentation and the TypeSpec playground
• templates/ for boilerplate servers (Express, Go, FastAPI)

While CommonGrants is the specification, the Simpler Grants Protocol is the delivery mechanism that ships, versions, and supports that specification.

Key Differences Between CommonGrants and Simpler Grants Protocol

Understanding the distinction between these two layers helps teams choose the right integration strategy. The differences span scope, artifacts, implementation, governance, and audience.

Scope and Definition

CommonGrants is narrowly focused on the API contract itself—endpoints, request/response schemas, and validation rules. It is a technical specification that answers the question: "What does a standards-compliant grant API look like?"

Simpler Grants Protocol is broadly focused on the entire ecosystem. It answers the question: "How do I build, test, deploy, and govern a CommonGrants-compliant system?" It includes the spec but adds the tooling to operationalize it.

Primary Artifacts

The CommonGrants artifact is the specification file itself, located at website/src/specs/main.tsp, along with the generated OpenAPI documentation.

The Simpler Grants Protocol artifacts are the repository contents under lib/ (Node & Python packages), website/ (docs & playground), and templates/ (boilerplate servers).

Implementation and Tooling

When implementing CommonGrants, developers use the specification to ensure their API returns the correct data shapes. However, CommonGrants itself provides no runtime tools.

The Simpler Grants Protocol provides the TypeScript SDK (lib/ts-sdk/src/client/opportunities.ts) for client interactions, the CLI (lib/cli) for validation, and middleware for server-side enforcement. For example, the SDK's Opportunities class implements the client-side interaction with the CommonGrants API:

// lib/ts-sdk/src/client/opportunities.ts
const opp = await client.opportunities.get("123e4567-e89b-12d3-a456-426614174000");
console.log(opp.title);

Governance Structure

CommonGrants governance is defined by the RFC process documented in website/src/content/docs/governance/. This process governs changes to the specification itself.

Simpler Grants Protocol governance is managed as part of the broader SimplerGrants initiative overseen by HHS, with additional governance documentation in website/src/content/docs/about.mdx. This covers not just the spec, but the tooling and community guidelines.

Target Audience

CommonGrants targets developers building API clients or servers that need a common data model for grant information. It is for implementers of the standard.

Simpler Grants Protocol targets project teams that need the full stack: the specification, SDKs, CI/CD pipelines, documentation site, and community guidelines. It is for adopters who need a complete toolkit.

Practical Examples

To illustrate the relationship in practice, consider three common development scenarios.

Using the TypeScript SDK to Call a CommonGrants API

The Simpler Grants Protocol provides the TypeScript SDK in lib/ts-sdk/src/client/opportunities.ts. This SDK allows developers to interact with any CommonGrants-compliant API using type-safe methods:

import { Client } from "@common-grants/sdk/client";
import { withCustomFields } from "@common-grants/sdk/extensions";
import { OpportunityBaseSchema } from "@common-grants/sdk/schemas";

// Create a client pointing at a CommonGrants API
const client = new Client({ baseUrl: "https://api.example.org" });

// Basic fetch – returns the base shape
const opp = await client.opportunities.get("123e4567-e89b-12d3-a456-426614174000");
console.log(opp.title);

// Fetch with a custom‑fields schema for typed access
const OpportunitySchema = withCustomFields(OpportunityBaseSchema, [
  { key: "legacyId", fieldType: "integer", valueSchema: z.number().int() },
] as const);
const typed = await client.opportunities.get("123e4567-e89b-12d3-a456-426614174000", {
  schema: OpportunitySchema,
});
console.log(typed.customFields?.legacyId?.value); // ← typed as number

This example demonstrates how the Simpler Grants Protocol (via the SDK) facilitates interaction with a CommonGrants API.

Defining a Route in a CommonGrants API with TypeSpec

The CommonGrants specification itself is defined using TypeSpec. The website/src/specs/main.tsp file shows how the core library is imported to expose standard endpoints:

// website/src/specs/main.tsp
import "@common-grants/core"; // pulls in the base spec

@route("/common-grants/opportunities")
opportunity get(id: Types.uuid): OpportunityBase;

This TypeSpec code compiles to the OpenAPI specification that defines the CommonGrants standard.

Running the CLI to Validate Against CommonGrants

The Simpler Grants Protocol includes a CLI tool for validation, located in lib/cli. Developers can use this to verify that their OpenAPI documents comply with the CommonGrants specification:

npx @common-grants/cli validate ./openapi.yaml

This command leverages the tooling provided by the Simpler Grants Protocol to enforce the CommonGrants standard.

Summary

• CommonGrants is the specification—a TypeSpec-defined open standard for grant API data models, endpoints, and validation rules, compiled to OpenAPI and JSON Schema.
• Simpler Grants Protocol is the ecosystem—the repository that bundles the CommonGrants spec with SDKs (TypeScript and Python), CLI tooling, templates, documentation, and governance processes.
• CommonGrants targets developers implementing the API contract, while Simpler Grants Protocol targets teams needing the full development stack, including client libraries and validation middleware.
• The relationship is hierarchical: CommonGrants lives inside the Simpler Grants Protocol repository, which delivers, versions, and maintains the specification.

Frequently Asked Questions

Is CommonGrants the same as the Simpler Grants Protocol?

No, they are distinct but related. CommonGrants is the open API specification that defines how grant data should be structured and exchanged. The Simpler Grants Protocol is the broader initiative and repository that contains the CommonGrants specification along with all supporting tools, SDKs, and documentation. As noted in the repository's documentation, CommonGrants lives inside the SimplerGrants initiative.

Where can I find the CommonGrants specification files?

The canonical CommonGrants specification is located at website/src/specs/main.tsp in the repository. This TypeSpec file imports the core library and defines the API endpoints, which are then compiled to OpenAPI specifications and JSON Schema. The generated documentation is also available in the website/src/content/docs/ directory, particularly in the about.mdx file which describes the protocol's scope.

What tools does the Simpler Grants Protocol provide?

The Simpler Grants Protocol provides a comprehensive toolkit including TypeScript and Python SDKs (located under lib/), a CLI tool for validating OpenAPI documents against the CommonGrants spec (in lib/cli), and server templates for Express, Go, and FastAPI (in templates/). It also includes the documentation website with a TypeSpec playground and the governance framework for managing changes to the specification.

How do I validate my API against CommonGrants?

To validate that your API implementation conforms to the CommonGrants specification, use the CLI provided by the Simpler Grants Protocol. Run the command npx @common-grants/cli validate ./openapi.yaml to check your OpenAPI document against the specification. This validation ensures that your endpoints, data models, and validation rules align with the CommonGrants standard defined in the TypeSpec files.

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