Stages at a glance
The vocabulary match column is key: the spec stages and the schema annotations are two views of the same state. If a JSON Schema in
static/schemas/source/ has "x-status": "experimental", the section it belongs to is at the Proposed stage. If it has no x-status marker and the schema has shipped in a GA release, it is at the Final stage.
Stage definitions
Draft
A section is in Draft when the working group has opened a scoped proposal on the GitHub milestone — aspec / protocol labeled issue with a defined scope — but no schema has been published in static/schemas/source/ yet. Draft sections:
- Carry no stability contract of any kind. Builders who proceed against a Draft section do so at their own risk and SHOULD track the relevant GitHub milestone for changes.
- Are not declared in
get_adcp_capabilities. A seller cannot claim conformance with a Draft section. - May be abandoned before reaching Proposed.
Proposed
A section is Proposed when its schema exists instatic/schemas/source/ with "x-status": "experimental" at the schema root or on the specific properties, and the seller implementing it declares the feature id in experimental_features on get_adcp_capabilities.
The full Proposed-stage contract — including what may change with 6-week notice, what does not change (auth, transport, error envelope), and the seller declaration requirements — is specified in Experimental Status. That page governs; this page maps stage vocabulary to it.
Entry: The schema is published in a 3.x release with x-status: experimental. The architecture committee review that accompanies the release confirms experimental status.
Decision authority: Architecture committee, at release time.
Final
A section is Final when its schema is stable —x-status: experimental has been removed via a deliberate graduation PR reviewed by the architecture committee.
The four graduation criteria are specified in Experimental Status — Graduation to stable — including the production signal requirement, cross-party validation bar (a second implementation running ≥45 days with at least one in production, or one implementation plus buyer integration), schema stability window, and the deliberate promotion PR. That page governs; this page maps stage vocabulary to it. The architecture committee reviews graduation PRs at each 3.x release.
Once Final, a section is protected by the full 3.x stability guarantees: fields are never removed, enums are additive only, task names are never removed or renamed within the major version. A Final section in 3.x remains Final — under the same guarantees — throughout the 4.0 development cycle. A section under active 4.0 scoping is not retroactively downgraded; the 3.x contract holds until 3.x support ends. See Support window for previous major.
Entry: All four graduation criteria from experimental-status.mdx are met. Architecture committee approves and merges the graduation PR in a scheduled 3.x release.
Decision authority: Architecture committee.
Deprecated
A section is Deprecated when a formal deprecation notice has been published in the release notes and changelog. The section remains fully functional and under the 3.x stability guarantees until the next major at the earliest. Its removal target is recorded in the schema withx-removed-in (for example, "x-removed-in": "4.0.0").
The deprecation policy is specified in Versioning — Deprecation policy. A deprecated feature is never removed within the major that deprecated it. A major may remove it with no minimum notice period, and the previous major’s support window protects implementers.
Entry: Deprecation notice lands in the release notes and changelog for a 3.x release. The replacement (if any) ships in the same release. The architecture committee confirms the removal target (always a major-version boundary).
Decision authority: Architecture committee, with working group review.
Announcement: Release notes entry with deprecated label + migration note, changelog entry, inline @deprecated annotation in the schema.
Sunset
A section is Sunset (removed) once the major-version boundary it was targeted for has shipped. By policy, a Deprecated section is never removed within the same major version — the earliest removal date is the GA of the next major. The v2 sunset timeline is documented on the v2 sunset page. Entry: The successor major ships GA. The previously-deprecated fields, tasks, or schema properties are omitted from the new major’s schemas. Decision authority: Implicit — the major-version release process carries the removal.Transition diagram
How to check the current stage of a spec section
- Schema marker: Check the relevant schema in
static/schemas/source/."x-status": "experimental"→ Proposed. No marker on a shipped schema → Final. Not instatic/schemas/source/but referenced in an open GitHub milestone issue → Draft. - Experimental surfaces list: The Experimental Status page lists every currently-Proposed surface with its feature id and current status.
- GitHub milestones: Open issues on the active milestone represent Draft and Proposed work. Shipped items without
x-statusin the merged schema are Final. - Release notes: Deprecated sections are called out with a
deprecatedlabel and removal target in every release’s notes.
Working group and governance
The procedures that govern who sits on the working group, voting thresholds, quorum, and escalation paths:- RFC process (#2437): proposal template, decision-record format, lifecycle from RFC to spec change
- Working group charter (#2438): quorum, voting thresholds, roster, recusal policy — under active development