a2aproject / a2aproject/A2A

Publish JSON Schema / OpenAPI bundle for Agent Card and core types

Open
#1,781 1 comment 1 reaction 0 assignees View on GitHub
triaged TSC Review
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.