Proposal: OAA 1.0 Versioning Transition

Status

Accepted for OAA 1.0

Summary

The initial stable specification release is 1.0.0; its manifests use schema_version: "1.0". All manifests in one archive use the same schema version, and implementations support explicitly recognized schema versions.

Motivation

OAA 1.0 needs an unambiguous version contract without treating version strings as implicitly ordered or changing the meaning of the published OAA 0.1 contract.

Specification Changes

• Every OAA 1.0 manifest MUST use schema_version: "1.0".
• All manifests in one archive MUST use the same schema_version.
• Implementations MUST explicitly recognize each schema version they support.
• Implementations MUST NOT infer compatibility by comparing schema version strings as higher or lower.
• Support for "1.0" MUST NOT be presented as automatic support for every future 1.x manifest version.
• OAA 0.1 archives are not OAA 1.0 Valid Archives.
• Implementations MAY provide explicit OAA 0.1 compatibility or migration handling, declared separately from 1.0 support. Legacy migration is not a 1.0 release prerequisite.
• Adding a required field, incompatibly changing existing field semantics, or adding a value to a closed base value set is a breaking change and requires a new major schema version.
• New optional fields MAY be added in compatible OAA 1.x revisions when they do not change existing semantics or required-field and closed-value contracts.
• Specification release tags use MAJOR.MINOR.PATCH. Release 1.0.0 establishes manifest version "1.0"; patch releases MUST NOT change schema_version, introduce new archive-validity requirements, or retroactively invalidate conforming archives.
• OAA 1.0 schemas use immutable, versioned identifiers.

Compatibility Impact

OAA 0.1 remains defined by the v0.1.2 release. Its schema and requirements remain available as versioned historical artifacts. OAA 1.0 schemas and requirements are added as separate versioned artifacts rather than overwriting the OAA 0.1 contract.

Examples

Specification release 1.0.0 uses the following manifest version. A subsequent 1.0.1 patch retains "1.0" and the same archive-validity contract.

{
  "schema_version": "1.0"
}

Open Questions

None for this decision.