Learn

Publish a Versioned Domain Specification

Publish a canonical Domain Specification version with the right route, source JSON, and supporting publication signals.

Procedure

Publishing a versioned Domain Specification

The versioned Domain Specification is the canonical document. Everything around it should reinforce that one public truth.

1Update canonical JSON

Publish the versioned source under the required `data/domain-specifications/` naming pattern.

2Validate against the root

Confirm the document still satisfies the Specification Root contract.

3Align routes and redirects

Make sure the canonical page and convenience route describe the same release.

4Refresh public page copy

Keep the visible route, version, and summary synchronized.

5Confirm support artifacts

Check that fixtures and support files still line up with the published version.

If the source, route, and support files disagree, the release is not truly published cleanly.

This guide is for the case where a domain has already been defined and you need to publish a new version cleanly.

The important idea is that the versioned Domain Specification is the canonical public document. Everything else should support that document, not compete with it.

  1. Update the canonical JSON source under data/domain-specifications/ using the repository naming convention.
  2. Verify that the document still matches the Specification Root contract.
  3. Confirm the versioned public route and any convenience redirect route point to the intended canonical page.
  4. Update the public page copy so the visible route, version, and summary all describe the same release.
  5. Confirm support artifacts and fixtures still line up with the published version.

Publication Checks

  • The source file uses the required flat naming pattern.
  • The public page reflects the exact version being published.
  • The route inventory still points readers to the canonical versioned surface.
  • The versioned page is easy to cite without relying on a convenience URL.

Avoid

  • Publishing a new version by editing only the human-facing page.
  • Leaving redirect targets and source JSON out of sync.
  • Using the convenience route as the long-term citation target when a versioned URL exists.