$ agentroot --protocol-version
AgentRoot protocol version history and backward compatibility.
Capability schema versioning
The protocol version is encoded as v=ar1 at the start of every _agentroot TXT record. This is the schema version for the TXT record format AND the JSON manifest schema. Records that don't start with a supported v= are ignored by the resolver.
Naming. The ar1 / ar2 tokens (short for AgentRoot v1, AgentRoot v2) are the on-the-wire version values. When people say "v1 of the capability schema" or "v2 schema", they mean ar1 and ar2 respectively — the literals match exactly so resolvers and humans don't have to translate.
Current version: ar1 (= "v1"), introduced 2026-02. It is the only supported version today; no ar2 exists or is in active development.
Deprecation timeline & backward compatibility. When ar2 ("v2") is introduced, the resolver will accept both ar1 and ar2 records concurrently for at least 12 months from the ar2 launch date. During the overlap, publishers can opt into the new version per-record by updating their TXT record's v= field; mixed deployments (some subdomains on ar1, others on ar2) are supported — the resolver dispatches per-record. ar1 records published today will continue to be valid until that 12-month overlap ends. We do not break ar1 before then.
Backward compatibility: zone= deprecation
Earlier versions of AgentRoot used zone=<url> to point to the JSON document. The current version uses manifest=<url> — semantically identical, but more accurate terminology (the JSON is a manifest of records, not a DNS zone file).
The resolver accepts both keywords. manifest= wins when both are present. New publishers SHOULD use manifest=; existing zone= records continue to work indefinitely (no planned removal date). This compatibility commitment is the model for how we'll handle future breaking changes — accept the old form, prefer the new, document the deprecation.
Reference: packages/api/src/infrastructure/adapters/dns.adapter.ts line 132.
Inline mode vs manifest mode
Two ways to declare records in _agentroot:
Manifest mode (recommended for 2+ records per domain):
Inline mode (works for single records, fits in DNS TXT 255-byte limit):
Both formats are fully supported in ar1. Inline mode is convenient for proof-of-concept and simple deployments; manifest mode scales to many records and supports richer metadata.
Migration path
Publishers using zone= should migrate to manifest= at their convenience. No data migration is required — the JSON file format is unchanged. Just update the TXT record: