# Versioning   Auto Agent Protocol uses [Semantic Versioning](https://semver.org/) (SemVer) for the published specification, schemas, and contract identifiers. The rules below are normative. ## SemVer policy Each released version of AAP has a major.minor version number (v0.1, v0.2, v1.0, v1.1, ...). The patch level is reserved for documentation-only fixes that do not change schemas, examples, or required behavior. | Change | Version bump | |---|---| | Adding a new optional field to an existing request or response schema | minor | | Adding a new skill | minor | | Adding a new optional behavior rule (SHOULD, MAY) | minor | | Adding a new error code | minor | | Removing a field, renaming a field, tightening a type, narrowing an enum | major | | Changing a required field's semantics | major | | Changing the agent-card extension URI (e.g. `extensions/a2a-automotive-retail/v0.2` -> `.../v1.0`) | major | | Documentation-only correction with no schema change | patch | The table above is the policy in force now that AAP has reached 1.0.0. **During the pre-1.0 (`0.x`) series, a minor bump was allowed to carry breaking changes** — per SemVer's 0.x allowance. v0.2 was exactly such a bump: it removed and renamed fields, flattened prices to integers, narrowed `status` to an enum, and dropped the separate contract manifest, all relative to v0.1. AAP v1.0.0 is the first stable release: its payload shape is the one introduced in v0.2, unchanged, now riding A2A v1.0. Pin to the exact version a dealer advertises. The AAP version lives in exactly one place on the wire: the agent-card extension URI (e.g. `https://autoagentprotocol.org/extensions/a2a-automotive-retail/v1.0`) and the schema `$id` URLs (`https://autoagentprotocol.org/v1.0/schemas/...`). Per-message `data.type` and `mediaType` are intentionally version-free; the dealer's agent-card pins the active version once per session. ## Released versions are immutable Once an AAP version is published at a stable URL (e.g. `https://autoagentprotocol.org/v0.1/`), the schemas, examples, and OpenAPI artifacts at that URL are frozen forever. Dealers and buyer agents that pin to `v0.1` can rely on the schemas not changing under them. Concretely: - `https://autoagentprotocol.org/v0.1/schemas/.schema.json` does not change after release. - `https://autoagentprotocol.org/v0.1/openapi-rest.yaml` and `https://autoagentprotocol.org/v0.1/openapi-jsonrpc.yaml` do not change after release. - The set of `data.type` identifiers defined in v0.1 (e.g. `inventory.search.request`, `lead.submit.response`) does not grow or change. - Documentation prose at `https://autoagentprotocol.org/docs/v0.1/` MAY receive editorial fixes, but cannot change normative content. ## The `latest` alias The path `https://autoagentprotocol.org/latest/` always aliases the highest released version. It is intended for browsing convenience, not for production wire pinning. Production agents SHOULD pin to a specific version (e.g. `v1.0`). How it is wired up today: - **Documentation**: `https://autoagentprotocol.org/docs/latest/` redirects (HTTP 200 client-side) to `/docs/v1.0/` via the Docusaurus client-redirects plugin. Every page reachable under `/docs/v1.0/` is also reachable under `/docs/latest/`. The frozen v0.1 and v0.2 docs remain served at `/docs/v0.1/` and `/docs/v0.2/`. - **Schemas, examples, OpenAPI, MCP manifest**: also served at `https://autoagentprotocol.org/latest/...` because the build pipeline mirrors `static/v1.0/` into `static/latest/`. The frozen v0.1 and v0.2 artifacts remain served at `https://autoagentprotocol.org/v0.1/...` and `https://autoagentprotocol.org/v0.2/...`. | URL form | Stability | Use case | |---|---|---| | `https://autoagentprotocol.org/v1.0/...` | Frozen | Production pinning. | | `https://autoagentprotocol.org/v0.2/...` | Frozen (historical) | Production pinning for agents still on v0.2; still served. | | `https://autoagentprotocol.org/v0.1/...` | Frozen (historical) | Production pinning for agents still on v0.1; still served. | | `https://autoagentprotocol.org/latest/...` | Tracks the highest released version (now v1.0) | Documentation browsing, not wire pinning. | | `https://autoagentprotocol.org/next/...` | Reserved | The current `docs/` is now v1.0; `next` will hold the preview of the next version once work on it begins. | ## Schema URL convention Every AAP JSON Schema lives at a version-pinned URL: ``` https://autoagentprotocol.org/v{version}/schemas/{filename} ``` Example for v1.0: - `https://autoagentprotocol.org/v1.0/schemas/inventory-search-request.schema.json` - `https://autoagentprotocol.org/v1.0/schemas/vehicle.schema.json` The `$id` inside each schema file matches its public URL. Schema cross-references (`$ref`) use relative paths within the same version directory. The AAP version is announced only via the agent-card extension URI and the schema `$id` URLs. There is no separate contract document; a buyer agent reads the extension URI to learn the version and then validates against the version-pinned schema URLs published by AAP. ## Extension URI The A2A extension URI is version-pinned per major.minor: ``` https://autoagentprotocol.org/extensions/a2a-automotive-retail/v1.0 ``` A future minor version introduces a new extension URI. Dealer agents that support multiple AAP minor versions MAY declare multiple extension entries on their A2A agent card; buyer agents pick the highest version they understand. ## Side-by-side versioning Dealer agents MAY run multiple AAP versions in parallel during a transition. Each version is exposed by a separate extension URI on the agent card; a dealer that speaks both v0.2 and v1.0 declares both extension URIs on its single agent card, and buyer agents pick the highest version they understand. ## Release process Each AAP release goes through three stages: 1. **Current (working)** — in-flight work lives in the current version directory (`spec/v1.0/`) and the Docusaurus `current` docs (`docs/`, served at `/docs/v1.0/`). Schemas and prose may change while the version is unreleased. 2. **`v{version}` (release candidate)** — schemas are frozen, prose may receive editorial polish. 3. **`v{version}` (released)** — schemas, prose, examples, and OpenAPI are immutable. The `latest` alias is updated to point here, and the docs are snapshotted into `versioned_docs/version-v{version}/`. The repository runs a `freeze-check` tool over released directories (`spec/v0.1/`, `spec/v0.2/`, `versioned_docs/version-v0.1/`, `versioned_docs/version-v0.2/`) on every PR to prevent accidental modification. ## What this means for buyer agents - Pin to a specific version (`https://autoagentprotocol.org/v1.0/`) in production. - Read the agent-card extension URI to learn the AAP version the dealer agent speaks. - Validate against the version-pinned schema URLs published by AAP — those URLs are version-pinned. - Do NOT assume cross-version compatibility. During the pre-1.0 series a minor bump could change shapes (v0.2 removed fields, flattened prices, and narrowed `status` relative to v0.1); v1.0.0 keeps the v0.2 payload shape unchanged but rides A2A v1.0. Speak the exact version a dealer advertises via its extension URI; a dealer that supports multiple versions declares each extension URI. ## What this means for dealer agents - Once you publish, freeze. Do not edit released schemas in place. - Develop changes against the current version directory (`spec/v1.0/`); cut them into a new version directory when you release. - Bump the version (and the agent-card extension URI's `v{major}.{minor}` suffix) for any breaking change. - Maintain the `latest` alias on your documentation host so casual browsers always land on the most recent published version.