Versioning & deprecation
The contract is versioned (the reference shows the latest v1; every
published version stays downloadable). Additive changes raise the minor version. Anything that
would break a client needs a new major path, never a silent change to /developer/v1.
Published versions
| Version | Status |
|---|---|
| 1.0.0 | Published. Stays downloadable. |
| 1.1.0 | Published. Latest v1. The reference and playground are generated from this document. |
Download any published version from the reference or directly:
openapi-1.0.0.yaml, openapi-1.0.0.json,
openapi-1.1.0.yaml, openapi-1.1.0.json,
openapi-latest-v1.yaml.
What changes safely
- Adding an operation, an optional field, or a new enum value that existing clients can ignore:
minor version bump, same
/developer/v1path. - Removing a field, changing a field's meaning or type, narrowing an enum, or changing error
shape: never done silently. These require a new major path (
/developer/v2) and a deprecation notice on the old one, with an announced sunset date. - Scopes only narrow across a refresh; they never widen without a new player consent.
Deprecation
A deprecated operation is marked x-release-status: deprecated in the contract before its
removal date, and keeps answering correctly until that date. The changelog
records every version and what changed.