URL scheme

Some links are cheap to fix and some are not. A link in a README is a pull request; a link inside a released binary’s error message is there until somebody upgrades, which for a compliance tool can be years. This page says which OpenRegs documentation URLs carry which promise, so that whoever writes the link knows what they are relying on.

Everything below describes docs.openregs.io, which is serving: DNS and TLS are live and every permalink in the table below resolves. The scheme was fixed before the host existed, because the links that are hardest to change are the ones being written today.

The three tiers

Permalinks — safe to embed anywhere

A short path this site promises to keep working for ever. The page it lands on may be renamed, merged into another, or rewritten from scratch; the permalink follows it. Treat one as API surface: it is fine in a shipped binary, an error string, a printed slide, a QR code.

Permalink	Lands on	Written for
/quickstart/	/guides/quickstart/	The first thing anyone should be told to read
/cli/	/reference/cli/	openregs --help and every subcommand epilog
/schema/	/reference/schema-compatibility/	schema_version mismatch errors

The set is deliberately tiny and grows slowly. A permalink is a promise nobody can withdraw, so a new one needs a reason of the same kind: a URL that will be baked into something unfixable. Everything else should link to the real path.

Permalinks live in redirects.json with the reason each one exists.

Section paths — stable, and moves are caught

The ordinary documentation URLs:

/overview/                      what OpenRegs is
/architecture/                  how it fits together
/glossary/                      vocabulary
/guides/<topic>/                task-shaped instructions
/integrations/<system>/         CI and platform wiring
/reference/cli/<command>/       generated from the CLI parser
/reference/api/<operation>/     generated from the serving API's route table
/reference/<topic>/             schemas, queries, compatibility
/runbooks/<procedure>/          operating and contributing procedures
/contributing/                  how to contribute, governance, security policy
/decisions/<id>-<slug>/         architecture decision records

These are stable in practice rather than by promise: a restructure may move one, but it cannot silently break it. Every route the site has ever served is recorded in routes.lock.json, and CI fails a build where a recorded route has stopped resolving and redirects.json does not say where it went. So an old section path either still serves the page or forwards to wherever the page went.

Link to these freely from anything you can edit — READMEs, issues, comments, other docs. Prefer a permalink only where editing later is impossible.

One address under /reference/api/ is not a page: /reference/api/openapi.json is the OpenAPI document the reference is generated from, published beside it so a client generator can read it. It is the engine repository’s own artifact, copied byte for byte at the commit the version was rendered from — so the copy under a frozen version’s prefix describes that version’s engine rather than today’s.

Version paths — pinned, and frozen on purpose

/                               latest: the current documentation
/v/<version>/                   a frozen version, cut at one engine commit

latest tracks the engine’s main and changes as core changes. A frozen version renders one specific engine commit and never changes again — it is the documentation for what somebody is actually running. Every page of one carries a banner saying so, and the version switcher above the navigation moves between them. Documentation versions is what a frozen version promises, and how one is cut.

No frozen version is served today, so every /v/… path is currently a 404. The prefix is reserved and the machinery is in place; there is nothing behind it until a version is next cut.

Version paths behave in a way the others do not, and in two ways that matter when you write one down. A page that exists in latest need not exist in a frozen version, because it may document something released after that version was cut. And a frozen version can be withdrawn: it is the one part of this scheme with no redirect behind it, because a frozen route is cut at an engine commit and cannot be re-pointed at a page describing a different one. Two versions have been withdrawn so far and their URLs 404. So use /v/<version>/… when the version is the point (a release note, a support answer about a specific build), know that it is the one prefix here that carries no promise of permanence, and otherwise link to the unprefixed path so the reader gets the current documentation.

Rules that hold everywhere

• Trailing slashes. Every documentation URL ends in /. The build emits directory-style routes and canonical links with the slash; write it that way and the link resolves without a redirect hop.
• Lowercase, hyphenated. Path segments are lowercase with hyphens between words. release-publish, never releasePublish or release_publish.
• Fragments are heading ids. #verifying-a-release is the slug of the heading text. Fragments are checked in CI along with the links, so a fragment that stops existing fails the build rather than scrolling to nowhere.
• No query strings. Nothing on this site is addressed by query parameter, so none should appear in a link to it.

Where a page’s content actually lives

Most pages here render Markdown from openregs/openregs at a pinned commit — documentation is written next to the code it describes and this site is the renderer. The footer of every such page names the exact file and commit it was rendered from, and “Edit this page” opens that file in the engine repository. A URL on this site is therefore not a place to send a documentation fix; the footer link is.