Versioning and Deprecation Policy

How AI Discovery File specifications are versioned, deprecated, and retired.

Status Stable

This policy is published and current. Changes propagate to every specification page because each one references this policy. See specification conventions for status definitions.

Last updated:

Purpose

This page is the single source for the project's versioning and deprecation rules. Every AI Discovery File specification follows these rules so publishers, validators, and consumers can rely on stable shape commitments and predictable change timelines.

1. Semantic Versioning 2.0.0

Each specification follows Semantic Versioning 2.0.0. Versions are numbered MAJOR.MINOR.PATCH and incremented per the rules below.

1.1 MAJOR (X.0.0)

A MAJOR increment signals a backwards-incompatible change. A publisher's previously-valid file MAY no longer conform to the new MAJOR version. Examples that justify a MAJOR bump:

A MAJOR release is accompanied by a deprecation window for the previous MAJOR version. See section 3.

1.2 MINOR (1.X.0)

A MINOR increment signals a backwards-compatible addition. A publisher's previously-valid file remains valid after a MINOR release. Examples:

MINOR releases are the most common. Phase work (per the spec standardisation roadmap) ships as one coordinated MINOR per phase.

1.3 PATCH (1.0.X)

A PATCH increment signals a backwards-compatible correction. No content was added; existing content was clarified or fixed. Examples:

1.4 Three-way version sync

Every specification exists in three parallel forms: the rendered specification page, the JSON data file (*-specification.json), and the YAML data file (*-specification.yaml). All three MUST carry the same meta.version at every release. The audit script enforces this.

The registry.json document carries each spec's current version in files[].version and MUST match versions.php after every release.

2. Specification lifecycle

Each specification carries a status badge near its header. Four status values are used; see conventions for the canonical definitions. The lifecycle below documents the transitions between them.

2.1 Draft

The specification is under active development and MAY change in incompatible ways before reaching Stable. Implementers SHOULD expect breakage. Drafts MUST NOT be cited as the authoritative form of the specification.

Transition out: when the editorial team is satisfied that the shape is stable, the specification is promoted to Stable in a release that bumps it to 1.0.0.

2.2 Stable

The specification is published and recommended for implementation. Backwards-compatible additions occur in MINOR releases; breaking changes require a MAJOR bump and the deprecation procedure in section 3.

The default expectation for a Stable specification is that it remains Stable indefinitely. There is no fixed end-of-life timeline.

2.3 Deprecated

The specification is still valid but discouraged for new implementations. A successor specification or replacement is published (or planned). Existing publishers SHOULD migrate before the Retirement date.

Validators MAY emit warnings for files conformant to a deprecated specification. The conformance class evaluation still passes (a deprecated file is still valid), but a diagnostic is added.

2.4 Retired

The specification is no longer maintained or recommended. Existing files MAY continue to function technically, but validators MAY treat conformance to a Retired specification as a failure. No further changes will be published.

3. Deprecation timeline

When a MAJOR version of a specification is released, the previous MAJOR version follows this deprecation schedule:

  1. Day 0: New MAJOR released, previous MAJOR enters Deprecated status. The deprecation is announced in the project changelog and in the affected spec's versionHistory[] entry. The successor link is added to the deprecated spec's page.
  2. Months 0 to 12: Deprecation window. Both versions remain available. Validators MAY warn on the deprecated version but MUST NOT fail it.
  3. Month 12: Retirement. The deprecated version moves to Retired status. Validators MAY now fail it. The spec page remains published as a historical document but no further changes are made to it.

The minimum 12-month window is a floor, not a target. Longer windows are appropriate for widely-deployed specifications.

A specification MAY also move directly to Retired without a Deprecated phase if it was Draft (never reached Stable) or if there's no successor (it's simply being withdrawn). In the latter case, the project changelog records the rationale.

4. Release cadence

The standardisation roadmap ships work in coordinated phases. Each phase concludes with a single MINOR release that bumps every touched specification, the umbrella definition version, and the visible changelog. Inside a phase, individual items don't get their own version bumps; this prevents version-sync drift across the PHP/JSON/YAML triplet of every spec.

PATCH releases ship as needed for typo fixes, broken-link fixes, or hot-fix wording corrections. They don't wait for a phase boundary.

5. Changelog

All releases are recorded in two places that stay in sync:

The format follows Keep a Changelog: Added / Changed / Fixed / Removed / Spec affected / Phase reference. Every release lists which specs were affected and which conformance classes they participate in (if relevant).

References