Source of truth for the shared schemas that power the Inference Gateway ecosystem - the OpenAPI HTTP API spec, the A2A (Agent-to-Agent) protocol, and the Model Context Protocol (MCP).
This repository holds the three shared schemas that the rest of the Inference Gateway ecosystem consumes. Downstream projects regenerate from these files, so a change here ripples into the gateway, the SDKs, the docs, the CLI, and the operator.
Two kinds of files live here:
- Sources of truth are hand-edited here (
openapi.yaml,a2a/a2a.proto). - Generated / mirrored files are produced by the tasks below and should never be hand-edited - change the generator input (or upstream) and regenerate.
| Schema | File(s) | Editing |
|---|---|---|
| OpenAPI | openapi.yaml |
Hand-edited; source of truth for the gateway's HTTP API. |
| A2A | a2a/a2a.proto → a2a/a2a-schema.{json,yaml} |
a2a.proto is the source of truth; the JSON/YAML are generated via task a2a-schema-download. |
| MCP | mcp/mcp-schema.{json,yaml} |
Mirrored from modelcontextprotocol/modelcontextprotocol via task mcp-schema-download. |
.
├── openapi.yaml # Inference Gateway HTTP API spec - source of truth
├── a2a/
│ ├── a2a.proto # A2A protocol - source of truth
│ ├── a2a-schema.json # generated from a2a.proto
│ └── a2a-schema.yaml # generated from a2a.proto
├── mcp/
│ ├── mcp-schema.json # mirrored from upstream MCP
│ └── mcp-schema.yaml # mirrored from upstream MCP
└── scripts/ # A2A generation pipeline (Bun)
These schemas are consumed across the inference-gateway:
inference-gateway- vendorsopenapi.yamlfor Go code generation.sdk,python-sdk,rust-sdk,typescript-sdk- client SDKs generated from these schemas.docs- API reference and guides.operatorandcli- consume the shared types.
The repository uses Bun as the runtime and package manager,
and all tasks run through Task. You can use
flox for a consistent toolchain (configured in
.flox/env/manifest.toml).
# Install dependencies
bun install
# List every available task
task --listCommon tasks:
| Task | What it does |
|---|---|
task openapi:lint |
Spectral lint of openapi.yaml (runs in CI). |
task openapi:format |
Format openapi.yaml with Prettier. |
task lint |
Markdownlint over the Markdown files (runs in CI). |
task format |
Format the YAML schemas with Prettier. |
task a2a-schema-download |
Regenerate the A2A schema from a2a/a2a.proto (needs Go + buf). |
task mcp-schema-download |
Sync the MCP schema from upstream. |
task release:dry |
Preview the next semantic-release version locally. |
See
CLAUDE.md/AGENTS.mdfor the full set of commands, the A2A generation pipeline, and contributor conventions.
Releases are automated with semantic-release
and triggered manually via the Release GitHub Actions workflow
(workflow_dispatch). The version is derived from the
Conventional Commits since the last
release, and each release updates CHANGELOG.md, creates a git
tag, and publishes a GitHub Release. Nothing is published to a package registry.
- Use Conventional Commits - semantic-release derives versions from the commit history.
- Edit
openapi.yamldirectly; it is the source of truth. - Never hand-edit generated or mirrored files (
a2a/a2a-schema.*,mcp/mcp-schema.*) - change the generator input and rerun the task.
Licensed under the Apache License 2.0.