Publish JSON Schema / OpenAPI bundle for Agent Card and core types
- Dominant language
- Shell
- Stars
- 25.7k
- Forks
- 2.6k
- Avg merge
- 3d 6h
- Merged PRs (30d)
- 16
Description
## Request
The A2A specification already notes that you *may publish an OpenAPI v3 + JSON Schema bundle for enhanced tooling* (alongside the canonical protobuf definition). This issue is a request to prioritize that.
## Why this matters
Agent manifests (e.g. `agent.json` files that describe an agent's identity, capabilities, and metadata) need to reference a `$schema` URL to validate their A2A-compatible fields. Without a published JSON Schema for the Agent Card, tooling authors are forced to either:
- Duplicate the type definitions manually (drift risk)
- Reference the TypeScript types or protobuf (not usable in JSON tooling)
- Invent their own schema (interoperability breaks)
A concrete example — an `agent.json` that wants to declare A2A-compatible top-level fields today cannot write:
```json
{
"$schema": "https://spec.a2aprotocol.ai/schemas/agent-card/v1.json",
"name": "My Agent",
"description": "..."
}
```
because no such schema URL exists.
## Proposal
Publish a JSON Schema file (or OpenAPI v3 bundle) for at minimum:
- `AgentCard`
- `Task` and task state types
- `TaskStatusUpdateEvent` and `TaskArtifactUpdateEvent`
The protobuf remains the normative source. The JSON Schema can be generated from it or maintained as a derived artifact, with a clear note that the protobuf is authoritative in case of conflict.
A stable URL pattern like `https://spec.a2aprotocol.ai/schemas/{version}/{type}.json` would allow agent tooling to reference specific versions.
## Context
We are building an AI agent platform that implements A2A for agent discovery and dispatch. We want to use `$schema` in agent manifests to make the provenance of each field explicit — which standard it belongs to — but cannot do so without a published schema URL.
Contributor guide
Assessment
This issue has not been assessed yet.