Compatibility and versioning

Capability schemas are versioned; the current index ishttps://gateway.agenticdealernetwork.com/spec/v2/envelope.json(the spec_index field of the network manifest is always the authoritative pointer). Each capability in the tool reference links to its schema.

Changes we make without notice

• Adding a new tool.
• Adding a field to an object whose schema permits extension.
• Adding a capability-tier entry.

Whether a given object permits extension is declared in its schema. Check the schema rather than assuming — some objects are closed.

Changes that get a new version

• Removing or renaming an output field, or changing its type.
• Changing what an existing field means.
• Adding an input parameter, or making an optional input required — tool inputs are closed objects.
• Removing a tool, or changing error codes or shapes.
• Adding a value to a closed enumeration — see below.

From v1 forward, breaking changes ship on a new version path served in parallel with the previous one for a stated window. (v0 predates this policy: it was retired at the v1 event of 2026-08-15, before the network had external integrators, and is preserved as a frozen baseline in the gateway repository rather than served.)

Normalized vocabularies

Vehicle data reaches ADN from many dealer feed vendors and dealer management systems. ADN normalizes that variance at ingestion, so the values you receive are stable and you may switch on them exhaustively. Vehicle condition is new or used; certification is a separate boolean.

Adding a value to one of these vocabularies would be a breaking change and would ship as a new contract version — not silently.

Object extension policy

Every object in the schema surface is deliberately declared open or closed; the schema is the authority, this table is the summary.

• Open (new fields may appear; ignore unknown keys): the shared data shapes unit, unit_summary, androoftop_public, and both discovery manifests (network and rooftop).
• Closed (a new member is a version event): the error object, the freshness object, every tool input, and every tool output wrapper. (Composed unit rows inside search results follow the open unit shapes above.) Closed inputs mean unknown arguments are rejected rather than ignored.
• The error code list and the manifest authvocabulary are closed enumerations: a new value ships as a new contract version, never silently.

v1 → v2 migration (2026-08-31)

v2 is the current contract version. This version event corrects a v1 deviation: the deal.quote family's pricing object gained members (pricing_coverage, excluded,pricing_disclosure, basis) after initial v1 publication without a version event. v2 declares that shape honestly — the members are part of the contract — and carries wording cleanups in several tool descriptions (no shape changes beyond the declaration above).

v1 remains served in parallel until at least 2026-10-01, byte-frozen as published. Migration action: re-point generated validators at /spec/v2/ (the manifest's spec_index already points there). Consumers still on v1 during the window should tolerate the four members above in the pricing object even though v1 declares it closed — that tolerance note retires with v1.