# CommonGrants vs Simpler Grants Protocol: Understanding the Architecture

> Compare CommonGrants an open API spec to Simpler Grants Protocol its full ecosystem of tools and governance. Understand their architectural differences.

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

---

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

```typescript
// 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`](https://github.com/hhs/simpler-grants-protocol/blob/main/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`](https://github.com/hhs/simpler-grants-protocol/blob/main/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:

```typescript
// 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`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/ts-sdk/src/client/opportunities.ts). This SDK allows developers to interact with any CommonGrants-compliant API using type-safe methods:

```typescript
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:

```typescript
// 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:

```bash
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.