UNIVIP

ADR-0008: Canonical URLs on univip.org and website generation

On this page

Status: Accepted 2026-10-14; decision 4 superseded by ADR-0009 on 2026-10-15 Date: 2026-10-14 Profiles affected: all (identifiers only; no behavioral change)

Notes (2026-10-15): Decision 1 gives the identifiers as they were for spec 0.1; spec 0.2.0-draft moved them to https://univip.org/schemas/v0.2/<kind>.schema.json under decision 5. ADR-0009 replaces decision 4 (MkDocs and GitHub Pages) with a Vite build hosted on Cloudflare, and with it the GitHub Pages consequences below. These notes change nothing else in this decision.

Context

The project sponsor purchased univip.org on 2026-10-14. Until then schema identifiers used URNs (urn:univip:schema:v0.1:<kind>) so that no domain was claimed before one existed. A real domain allows stable, dereferenceable identifiers and a website generated from the repository.

Decision

  1. Schema $ids are https://univip.org/schemas/v0.1/<kind>.schema.json. Cross-references use these URLs. The schema member inside messages keeps the short form univip.<kind>.vX.Y; it is a name, not a URL.
  2. The website publishes each schema at exactly its $id, the OpenAPI document at https://univip.org/api/v1/univip-v1.openapi.yaml, and the specification at https://univip.org/spec/<version>/....
  3. Implementations MUST NOT fetch schemas at runtime to validate messages; they ship the schemas they were tested with. The URLs are identifiers and documentation locations, not a runtime dependency. The reference validator preloads a local registry.
  4. The website is generated from this repository by CI (MkDocs, configuration in site/), deployed to GitHub Pages with the custom domain univip.org. The repository stays the single source of truth; nothing is edited on the website directly.
  5. Versioning: a new MINOR schema version gets a new directory (/schemas/v0.2/); existing URLs never change content once a version is tagged Stable.

Consequences

  • One-time edit of every $id and $ref (done in the same commit as this ADR). tools/validate.py is unaffected because it keys the registry on $id.
  • DNS for univip.org must point at GitHub Pages (A/AAAA records for the apex and a www CNAME) and HTTPS enforced in the repository's Pages settings. This is a one-time manual step for the repository owner; site/README.md lists the records.
  • The MIME type for .schema.json on GitHub Pages is application/json, which is acceptable; application/schema+json is preferred and can be set if hosting moves.

Generated from docs/decisions/ADR-0008-canonical-urls-and-website.md.