Where to Find CommonGrants Documentation and OpenAPI Specs

The CommonGrants documentation and OpenAPI specifications are available both in the hhs/simpler-grants-protocol repository and on the public website at commongrants.org.

The CommonGrants protocol provides standardized grant data exchange formats and API specifications. Whether you are implementing a grants management system or building a client application, you need access to the human-readable documentation and the machine-readable OpenAPI specifications. This guide maps out every location where these resources live, from the public website to the exact source files in the repository.

CommonGrants Documentation Locations

Human-Readable Protocol Documentation

The authoritative protocol specification lives in the repository's documentation source and is rendered on the public site.

• Repository path: website/src/content/docs/protocol/specification/v0_1_0.md
• Public URL: https://commongrants.org/protocol/specification

This file contains the human-readable description of routes, status codes, and data models that define the CommonGrants protocol.

Getting Started Guides

For developers looking to compile TypeSpec definitions into OpenAPI documents, the quick-start guide provides step-by-step instructions.

• Repository path: website/src/content/docs/getting-started.mdx
• Public URL: https://commongrants.org/getting-started

This guide explains how to use the CommonGrants CLI to compile TypeSpec definitions and generate OpenAPI specifications locally.

OpenAPI Specification Files

Published OpenAPI YAML Files

The canonical OpenAPI 3.0 documents are versioned and stored as static YAML files in the repository. These files are the source of truth for API implementations.

• Repository paths:

  • website/public/openapi/openapi.0.1.0.yaml
  • website/public/openapi/openapi.0.2.0.yaml
  • website/public/openapi/openapi.0.3.0.yaml

• Public URLs (replace version number as needed):

  • https://commongrants.org/public/openapi/openapi.0.1.0.yaml

These YAML files fully describe the CommonGrants API endpoints, request/response schemas, and authentication requirements.

Interactive API Documentation

For browsing the OpenAPI specs interactively, the website hosts a Swagger UI interface.

• Repository path: website/src/pages/protocol/api-docs.astro
• Public URL: https://commongrants.org/protocol/api-docs

This Astro page renders the static OpenAPI YAML files using Swagger UI, allowing developers to explore endpoints and download client SDKs directly from the browser.

Source Files and TypeSpec Definitions

Core TypeSpec Library

The authoritative source of truth for the protocol is written in TypeSpec, a domain-specific language for API definition. These files generate the OpenAPI specifications.

• Repository path: lib/core/*.tsp (e.g., lib/core/common_grants.tsp)

These TypeSpec files define the routes, models, and status extensions that are compiled into the OpenAPI YAML files found in website/public/openapi/.

CLI Compilation Tools

To regenerate the OpenAPI specs from TypeSpec source, use the CommonGrants CLI.

• Repository path: lib/cli/

The CLI package @common-grants/cli provides the cg compile command, which reads tspconfig.yaml (found in templates/quickstart/tspconfig.yaml) and emits OpenAPI 3.0 documents.

How to Access CommonGrants Documentation Programmatically

You can fetch the OpenAPI specifications directly via HTTP for use in automated tooling or client generation.

Fetch the OpenAPI Spec with Node.js

// Retrieve the latest OpenAPI document from the public site
const url = 'https://commongrants.org/public/openapi/openapi.0.3.0.yaml';
fetch(url)
  .then(res => {
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    return res.text();
  })
  .then(yaml => {
    console.log('OpenAPI spec loaded successfully');
    // Feed the YAML to a Swagger parser or client generator
  })
  .catch(err => console.error('Failed to load spec:', err));

Replace 0.3.0 with your target version number to access specific releases.

Generate the OpenAPI Spec Locally

# Install the CommonGrants CLI globally

npm install -g @common-grants/cli

# Compile TypeSpec to OpenAPI (requires tspconfig.yaml in your project)

cg compile --emit @typespec/openapi3 --output ./openapi.yaml

This command generates an openapi.yaml file matching the specifications found in website/public/openapi/.

Validate the Spec with Swagger Parser

const SwaggerParser = require('@apidevtools/swagger-parser');

SwaggerParser.validate('https://commongrants.org/public/openapi/openapi.0.3.0.yaml')
  .then(api => {
    console.log('OpenAPI spec is valid:', api.info.title);
  })
  .catch(err => console.error('Validation error:', err));

Summary

• Public website: Visit commongrants.org for human-readable docs at /getting-started and interactive API docs at /protocol/api-docs.
• Raw OpenAPI files: Download versioned YAML specs from website/public/openapi/openapi.0.x.x.yaml or via public URLs.
• Source of truth: TypeSpec definitions in lib/core/*.tsp generate the OpenAPI specs using the CLI in lib/cli/.
• Repository docs: Markdown specifications live in website/src/content/docs/protocol/specification/ and website/src/content/docs/getting-started.mdx.

Frequently Asked Questions

Where is the CommonGrants OpenAPI spec hosted publicly?

The CommonGrants OpenAPI specifications are hosted at https://commongrants.org/public/openapi/openapi.0.x.x.yaml, where you replace 0.x.x with the desired version number (e.g., 0.3.0). These files are also rendered interactively at https://commongrants.org/protocol/api-docs using Swagger UI.

How do I generate the OpenAPI spec from TypeSpec source?

Install the @common-grants/cli package and run cg compile --emit @typespec/openapi3 --output ./openapi.yaml from a directory containing a tspconfig.yaml file. This compiles the TypeSpec source files found in lib/core/ into a valid OpenAPI 3.0 document matching the published specifications.

What version of the OpenAPI specification does CommonGrants use?

CommonGrants publishes OpenAPI 3.0 documents. The repository maintains versioned specifications (e.g., 0.1.0, 0.2.0, 0.3.0) in website/public/openapi/, with each YAML file conforming to the OpenAPI 3.0 standard for API description and client generation.

Can I view the CommonGrants documentation offline?

Yes, all documentation source files are available directly in the repository under website/src/content/docs/. You can read the Markdown and MDX files (such as getting-started.mdx and protocol/specification/v0_1_0.md) locally without building the site, or run the Astro development server to browse the full documentation offline.

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