---
title: "Versioning"
description: "Additive and breaking changes, the protocol id, the path policy and the release-notes process."
image: "https://docs.agentregistrar.dev/og/docs-default.png"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.agentregistrar.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Versioning

`agent-identity-v1` carries its major version in the discovery document's `protocol` field. This page explains how the protocol changes and how the docs site tracks it. The normative policy is [spec section 13](/agent-identity/v1/specification/#13-versioning-extension--deprecation-policy).

## Current version

- Protocol id: `agent-identity-v1`.
- Specification release: `v1.2.0`, released 2026-10-24.
- Package: `@agentregistrar/discovery` `1.2.0`.
- The `v1.2.0` release adds Contracts G/H/I, the optional `rp_attestation`, the trust model and policy matrix, RP-signed receipts, authenticated Contract F and D.2, and the separate conformance/verification validator result. It removes no required field.
- `v1.0.0` and `v1.1.0` implementations remain conformant. Absence of `rp_attestation` means **unverified**, never invalid.

The full release history is in the [changelog](/agent-identity/v1/changelog/).

## Additive changes

Additive identity fields and clarifications are allowed within v1. They do not change the `protocol` value or the discovery path.

- Consumers must ignore unknown fields.
- Producers should namespace non-capability vendor metadata under `extensions.<reverse-dns>`.
- An additive change must pass the [scope-boundaries review checklist](/agent-identity/v1/scope-boundaries/#7-future-change-review-checklist).
- Additive changes are recorded in the specification changelog and the release notes.
- The schema, the JSON Schema and the validator are updated together so they cannot drift.

Vendor catalogs, provisioning endpoints, resource metadata and API-usage documentation are not additive protocol fields at any version. They belong in the post-signup guide.

## Breaking changes

A breaking change must use a new `protocol` value and a new discovery path, for example `agent-signup-v2.json`.

- The v1 path must not silently change semantics.
- A future version should be dual-published during a migration window.
- The public specification URL should be versioned. The optional `spec` field lets agents and humans find the exact document.
- The registry lists implementations by the `protocol` value their discovery document advertises.

## Path policy

The docs site follows the protocol path:

- `/agent-identity/v1/` is the canonical path for this major version.
- A breaking change would add `/agent-identity/v2/` rather than rewriting the v1 pages.
- There is no whole-site versioning. Only the protocol family is path-versioned.
- The generated pages under `/agent-identity/v1/` are pinned to one spec tag and are regenerated by `pnpm sync:spec`.

## Deprecation and release notes

- v1.2.0 does not deprecate v1.0.0 or v1.1.0. It is an additive revision.
- The specification's changelog records every additive v1 change with its date.
- Release notes record the release evidence, the change process and any non-blocking follow-ups.
- v1 has no formal sunset date. A future breaking change would be dual-published during a migration window; v1 would stay published for that window.
- A deprecation notice, if one is ever needed, belongs in the release notes and at the top of the affected version's landing page. The docs site does not invent a deprecation schedule ahead of the specification.

## Updating the rendered docs

The rendered pages are generated from a pinned tag, never hand-edited. The version-bump runbook is in the docs repository's `AGENT.md`:

1. Confirm the spec tag and release notes exist; read the diff.
2. Update `spec.lock.json` `tag` and let the sync resolve the commit and hashes.
3. Run `pnpm sync:spec`; review the generated diff for normative changes.
4. Update the hand-authored protocol pages if fields, errors or claims changed.
5. Update the changelog and any current-version strings.
6. Run the build, check, lint and theme gates; verify the schema `$id`.
7. Commit the lock, the generated pages and the hand-authored changes together.

## Known limits

- There is no formal deprecation timetable for v1.
- Additive changes do not change the wire protocol id, so an agent cannot tell minor versions apart from `protocol` alone. The optional `spec` field is the version pointer.
- The docs site renders one pinned tag. A newer tag is not live until the sync and review land.

## Related

- [Versioning, extension and deprecation policy](/agent-identity/v1/specification/#13-versioning-extension--deprecation-policy)
- [Release notes and changelog](/agent-identity/v1/changelog/)
- [Specification](/agent-identity/v1/specification/)

Source: https://docs.agentregistrar.dev/agent-identity/v1/versioning/index.mdx