Versioning policy

How the three YieldFabric public API specs version, what triggers a major / minor / patch bump, and what guarantees a consumer can rely on.

Per-service versions, one platform

Each service has an independent info.version in its OpenAPI spec and its own CHANGELOG. There is no platform-wide API version — clients pin to the per-service versions they integrate against.

All three use SemVer 2.0: MAJOR.MINOR.PATCH.

Bump rules

Patch (X.Y.Z → X.Y.Z+1)

Non-breaking corrections. No SDK regeneration required, no client changes required.

• Typo fix in a description
• Clarified prose
• Fixed example that didn't compile
• Regenerated code sample
• Updated error-catalogue prose (without adding/removing codes)
• Drift fix where the doc said X and the code did Y — bringing doc in line with code that hasn't changed

Minor (X.Y.Z → X.Y+1.0)

Additive, backward-compatible. SDK regeneration recommended but existing client code keeps working.

• New operation / endpoint
• New optional input field
• New optional response field
• New enum value (consumers should switch on known values and accept-but-ignore unknowns — see "Forward compatibility" below)
• New error code
• New example
• New guide

Major (X.Y.Z → X+1.0.0)

Breaking. Existing client code may fail. Requires migration.

• Renamed operation
• Removed operation, field, or enum value
• Required field became required (was optional)
• Optional field became required-in-some-contexts
• Type narrowing (e.g. string → enum)
• Auth requirement changed on an endpoint
• HTTP status code changed for an existing case
• Error code removed or renamed

Pre-1.0 caveat

All three services are currently pre-1.0 (0.x.y). SemVer allows breaking changes on minor bumps below 1.0, but we don't do that — the three services follow strict bump rules even pre-1.0 so consumers can rely on the contract.

The 0.x line will turn over to 1.0 when:

1. The spec is considered stable for external consumers.
2. SDKs are generated and shipped.
3. The deprecation policy below has been exercised at least once (so we know the playbook works).

Cross-service version compatibility

The services are independently versioned but the platform deploys them together. When one public surface changes in a way another YF surface depends on, YieldFabric handles the rollout order:

1. Producer ships a minor version exposing the new shape alongside the old.
2. All consumers update to use the new shape.
3. Producer ships a major version removing the old shape.

In practice this means breaking cross-surface changes need a deprecation cycle (see below).

Deprecation policy

When a field, operation, or error code is removed in a major bump, it follows this lifecycle:

deprecated → removed
   ↑          ↑
   announce   one minor version cycle later AT MINIMUM

The minimum deprecation window is one minor version cycle (typically 2-4 weeks for active services).

How a deprecation is announced:

1. Spec annotation. OpenAPI 3.1 supports deprecated: true on operations and deprecated: true in schemas. Both are honoured.
2. CHANGELOG entry under the minor version that adds the replacement, explicitly listing the deprecated thing and its replacement.
3. description: prose explaining the migration path.

Example:

/auth/old-endpoint:
  post:
    operationId: oldOperation
    deprecated: true
    summary: (DEPRECATED) Old shape — use POST /auth/new-endpoint instead.
    description: |
      Scheduled for removal in v1.0.0. Migrate to
      `POST /auth/new-endpoint` (same input shape, returns the
      replacement type).

Forward compatibility — what consumers should assume

Consumers SHOULD write code that survives minor bumps:

• Treat enums as open-ended. When you receive an enum value you don't recognise, accept-and-ignore (or surface as "unknown" in UI), don't throw. New enum values arrive on minor bumps.
• Don't deserialise into strict types that fail on unknown fields. Use lenient deserializers (#[serde(default)] on Rust, JsonSerializer without disallowUnknownProperties in TS, etc.).
• Switch on error code, not error message. Messages are free-form and may shift between releases. Codes are the stable contract.
• Respect Retry-After headers. If introduced, they're authoritative even if not previously specified.

Consumers MAY assume:

• HTTP status codes don't change for existing error cases.
• required fields stay required.
• Operation IDs don't change.

Pinning recommendations

How to pin per audience:

In the JS workspace, OpenAPI specs aren't versioned as npm packages today. If/when SDKs ship, they'll follow standard npm SemVer.

Change logs as the canonical record

Each service's CHANGELOG.md is the authoritative version log. Format:

## [X.Y.Z] — YYYY-MM-DD

### Added (minor)
- New endpoint / field / enum value with a 1-line description.

### Changed (minor — additive) or (major — breaking)
- What changed, why, migration path if breaking.

### Fixed (patch)
- Drift between doc and code; typo; example fix.

### Deprecated
- Things on the path to removal in the next major, with target version.

### Removed (major)
- Things gone; what replaces them.

Entries always lead with the change type. Major bumps surface the breaking changes at the top of the file with a "Breaking changes" header.

What's NOT versioned

• Repo-root README.md and CLAUDE.md. Internal docs; versioned implicitly by git history.
• docs/architecture/ trees. Internal; same.
• docs/getting-started/. Tutorial content; live with the spec, not separately versioned.
• Webhook payloads for outbound webhooks (when they exist). Each webhook event type is versioned via an event_version field in the payload, separately from the spec version.

Out of scope

• API gateway version (Apollo Router config). Operator concern, not consumer-facing.
• Database schema versions. Internal; never exposed to API consumers.
• Internal library versions. Workspace versioning, not API versioning.

See also

• docs/getting-started/cross-service-walkthrough.md — how the services compose at the consumer level.
• Per-service CHANGELOG.md files in each service's docs/api/.