limlock

spec · v0.1 · experimental · last updated

Versioning policy

Limlock's spec uses aggressive transparent versioning. Breaking changes on a public spec that a third party has integrated against is the failure mode that turns protocol evangelism into protocol liability. The policy below is conservative and caller-friendly by design.

Stages

v0.x — experimental
Schema and wire format may change. Implementations should not pin production integrations to a v0.x version without an explicit migration plan. Breaking changes may land in any minor revision; deprecations are best-effort.
v0.x — draft
Externally validated by at least one third-party emitter. Schema is structurally stable; field renames are still possible but rare and announced. Targeted at early adopters who can absorb migration churn for a quarter or two.
v1.0 — stable
Reached only after production usage has validated the shape. Once at v1.0, breaking changes follow the deprecation policy below — no field removed in less than one stable cycle from announcement.

Deprecation policy

  • v1.0 onward: a breaking change requires a deprecation notice at least 6 months in advance of removal. Notices live both in the spec changelog and as a X-Limlock-Deprecation response header on the reference implementation.
  • Field additions are non-breaking and may land in any minor version. Consumers must ignore unknown fields rather than rejecting the payload.
  • Field renames are breaking. The old name remains accepted for the deprecation window; the new name takes precedence when both are present.
  • Removals require a deprecation notice and a complete migration path documented in the spec changelog.

Today (v0.1)

Status v0.1 is experimental. The schema is the working contract for the reference implementation, but field renames or additions may land at any time without prior notice. Once a third-party emitter adopts the schema and Limlock has end-to-end production usage, v0.2 draft will follow with stricter discipline.

Versioning is enforced at the schema URL: future revisions live at /spec/v0.2/..., /spec/v1.0/..., etc. The current revision is always linked from /spec.

Why this matters

A schema becomes infrastructure when third parties integrate against it. The cost of a breaking change scales linearly with the number of integrations and quadratically with the time-since-integration. Aggressive transparent versioning — admitting v0.1 is experimental, refusing to call anything stable until it's validated — keeps the cost low while the protocol is still finding its shape.

The reference is the Stripe template, not the FHIR template. Ship a schema so obviously well-designed the ecosystem copies its shape; tighten the versioning bolts before any of those ecosystem copies see real production load.