How the registry works

How the registry is laid out

Every published document is stored under registry/ at the path derived from its identifier and version: registry/{country}/{subdivision?}/{authority}/{process}/{version}/schema.json. A version directory holds the document itself and, where one has been published, a VERIFICATION.md source-review record alongside it. The path is reconstructible from the document's id and version alone, so a name fully locates an entry.

Because a published (id, version) is immutable, a process accumulates a directory per version over time. Consumers browse by jurisdiction and authority, pin to a specific version, and read the verification record before relying on a schema.

The machine-readable catalog

The build publishes registry/index.json: one record per schema id at its latest version, carrying its title, status, all published versions, jurisdiction, authority, category, process type, and the path to its schema.json. Facet values are fields in this catalog — an agent never needs to parse them out of ids or scrape the registry browser, which renders from the same catalog.

Every entry also has a generated reference page at registry/{id} — identity, field reference, verification record, version history, and related schemas — with pinned pages per published version at registry/{id}/{version}.

Worked example

See the U.S. passport renewal (DS-82) reference for the full page pattern: identity and version, the field reference, the verification record, and version history. It is published in the registry at registry/us/dos/passport-renewal-ds82/.