MoreLogin publishes a machine-readable contract snapshot version in every OpenAPI document's info.version. The version uses calendar format YYYY-MM-DD and identifies the documentation contract, not a version segment in the request URL.
| Change | Classification | Documentation treatment |
|---|---|---|
| Add an optional request field, response field, operation, or enum value | Additive | Record in the changelog and update all localized specifications |
| Clarify descriptions or correct an example without changing runtime behavior | Documentation correction | Record when it changes integration guidance |
| Make an optional field required, remove/rename a field or operation, narrow accepted values, or change established semantics | Breaking | Provide a migration path and a separately versioned contract before removal |
Mark an operation with deprecated: true | Deprecation | Document replacement, announcement date, and planned removal date when one is approved |
Clients should ignore unknown response fields and enum values where their business logic permits. This reduces breakage from additive releases.
The OpenAPI operation is the authoritative machine-readable location. A deprecated operation must include:
deprecated: true- a description naming the replacement or stating that none exists
- an announcement entry in the API changelog
- a planned removal date only after the product and gateway owners approve it
No universal minimum deprecation period is currently guaranteed. Until a removal date is explicitly published, clients should treat the operation as supported but schedule migration away from it.
Runtime behavior remains authoritative. OpenAPI, examples, localized copies, the endpoint behavior manifest, and changelog are checked together in CI to prevent contract drift.
A passing repository quality gate proves that the OpenAPI files, examples, links, localized copies, and governance artifacts are internally consistent.
A rendered-page check proves that representative documentation routes load and display without client-side errors.
Only a credentialed smoke test against the deployed API can prove that production behavior matches the published contract. This repository does not run that test by default, so release notes must state separately when production verification was performed.