Spec Gap: adcp_version exists in production but is undocumented — and there's no version negotiation story

[scr-oath]

Spec Gap: adcp_version exists in production but is undocumented — and there's no version negotiation story

Category: Ideas — Spec Gap / Pre-3.0 GA

What we found

Upgrading our Media Buy server (Yahoo) from 2.5 → 3.0, we noticed that our agent-card already declares adcp_version in the ADCP extension block:

{
  "capabilities": {
    "extensions": [{
      "description": "Ad Context Protocol (ADCP) support",
      "params": {
        "adcp_version": "2.5.0",
        "protocols_supported": ["media_buy", "creative", "signals"]
      },
      "required": false,
      "uri": "https://adcontextprotocol.org"
    }]
  }
}

Searching the spec docs, adcp_version is not formally defined anywhere — not in the versioning reference, not in the implementor FAQ, not in the agent-card guidance. It exists in at least one production implementation but appears to be an undocumented convention.

This matters because even if we formalize adcp_version, it only solves half the problem.

The actual gap

The spec covers how the protocol evolves (version tiers, deprecation policy, release cadence) but says nothing about how a client and server negotiate compatibility when they're at different versions.

With a single adcp_version field and no range or negotiation mechanism:

• A server that upgrades to 3.0 has no way to signal it's still backward-compatible with 2.5 clients
• A client has no way to declare which version its payload conforms to
• The only safe upgrade path is simultaneous cutover across all parties

That works in hand-held pilots. It breaks down as the ecosystem scales — and with 4.0 on the 2027 horizon and longer version cycles planned, the window of mixed-version coexistence will only grow.

Precedent

A2A v1.0 shipped exactly this pattern:

• AgentCard advertises multi-version support simultaneously
• Clients declare which version they're sending per-request
• SDKs are required to provide version negotiation tooling

AdCP can adopt this directly, since it already sits on top of A2A's extension mechanism.

Proposed fix — two steps, minimal delta

Step 1: Formally specify adcp_version — document what's already in the wild as a normative field.

Step 2: Add adcp_versions_supported and per-request version declaration:

"params": {
  "adcp_version": "3.0.0",
  "adcp_versions_supported": ["2.5", "3.0"],
  "protocols_supported": ["media_buy", "creative", "signals"]
}

Clients declare their payload version per-request via either:

• HTTP header: AdCP-Version: 2.5
• JSON-RPC metadata field in the request envelope

This is the pattern used by Stripe, GitHub, and others. It's well understood, easy to implement, and lets servers go first — upgrade, declare multi-version support, and let clients migrate on their own schedule.

Server behavior: read the declared version, validate against adcp_versions_supported, route to the appropriate handler. If the declared version is unsupported, return a structured error with the supported range.

SDK implications

Server-side libraries should bundle all supported schema versions as a discriminated union — not separate installs. Pydantic v2 / Zod both support this cleanly. The version header/field drives which schema validates the incoming payload.

The ask

With 3.0 GA targeted for April 2026, we're asking for one of:

1. A normative spec change to the ADCP extension params (preferred — small delta, high value)
2. At minimum, a non-normative guidance section on client/server version compatibility

Happy to draft a PR for either. Is this the right place, or should this go to the architecture committee directly? And can we get a working group slot before GA?

Related: A2A version negotiation spec — https://a2a-protocol.org/latest/specification/#versioning

[bokelley]

Thanks for raising this — the underlying concern (mixed-version coexistence as the ecosystem scales) is real and worth addressing before GA.

What v3 already covers

The agent card extension (adcp-extension.json) was removed in v3. Version and capability discovery now happens at runtime via get_adcp_capabilities, which returns:

{
  "adcp": {
    "major_versions": [2, 3]
  }
}

This is the multi-version advertisement you're asking for in Step 2 — a seller can declare support for multiple major versions, and a buyer reads this before sending any requests. So the discovery side is already solved. Your agent card example is v2 — if you're upgrading to 3.0, you'd move to get_adcp_capabilities and declare "major_versions": [2, 3] during the transition.

What was missing (now addressed)

The per-request version declaration was referenced in the schema description but not formalized. #1959 adds:

• adcp_major_version integer field on the get_adcp_capabilities request — buyer declares which major version its payloads conform to
• VERSION_UNSUPPORTED error code for when the declared version is outside the seller's supported range
• Version negotiation documentation in both the capabilities reference and versioning guide

When omitted, the seller assumes its highest supported version (backward compatible with existing implementations).

Why major versions only

We intentionally skip minor/patch negotiation. Semver policy guarantees backward compatibility within a major version — a seller at 3.1 can serve a buyer at 3.0 without negotiation.

Features over versions

The more important point: AdCP's capability model gives you finer granularity than version negotiation. A seller doesn't just say "I support v3" — it declares exactly which protocols, features, targeting systems, execution integrations, and extensions it supports. Not every seller at v3 will support every v3 feature. Not every buyer needs every feature. The right compatibility question isn't "are we on the same version?" — it's "do you support what I need?"

The capability contract is explicit: if a capability is declared, the seller MUST honor it.

On the discriminated union SDK pattern

We'd recommend against bundling all schema versions as a single discriminated union. AdCP has dozens of schemas per major version — a union across all of them is impractical. The simpler pattern: server reads the declared version, routes to the appropriate handler, each handler uses its own schema set.

PR

See #1959 for the implementation. Happy to take feedback there.