SPECIFICATION · DRAFT v0.3

Identifiers & versioning

Identifiers and versioning are the parts of the standard that are hardest to change once schemas and consumers depend on them. This page describes how a process is named, how that name maps to a registry location, and how document versions evolve.

One-way-door conventions, conservative by design

The identity conventions below are deliberately conservative because consumers hard-code them. The identifier grammar is fixed by the published v0.1 meta-schema: a lowercase, slash-delimited registry path with no scheme prefix. The whole specification is still draft, so the grammar may evolve before v1.0, but the versioning rules and the principle of a stable, version-independent process identifier are settled — treat the specific spelling as draft until v1.0.

The GovSchema identifier (GSID)

Every document has a globally unique identifier in its id member that names a process across all of its versions — the GSID does not include the version. It is a lowercase, slash-delimited path with no scheme prefix, matching ^[a-z]{2}(/[a-z0-9-]+){2,}$:

{country}/{authority}/{process} — where {country} is an ISO 3166-1 alpha-2 country code, {authority} is a stable lowercase slug for the issuing body, and {process} is a stable lowercase slug for the form or process. A subnational process inserts a subdivision segment after the country, e.g. us/ca/dmv/vehicle-registration-renewal. The id equals the document's path under registry/ excluding the version.

text GSID examples and their registry paths 
id    us/dos/passport-renewal-ds82
path  registry/us/dos/passport-renewal-ds82/1.0.0/

id    gb/hmpo/passport-renewal-adult
path  registry/gb/hmpo/passport-renewal-adult/1.0.0/

id    us/ca/dmv/vehicle-registration-renewal
path  registry/us/ca/dmv/vehicle-registration-renewal/1.0.0/

Registry path mapping

When published, a document is stored at a path derived deterministically from its id and version: registry/{country}/{subdivision?}/{authority}/{process}/{version}/schema.json. This mapping is normative — the path must be reconstructible from the document's id and version alone — so the same name locates the file, the directory, and the record.

Document versioning (SemVer)

The version member is a Semantic Versioning 2.0.0 string for this document's content. The change that an increment represents is fixed by the rules below, so a consumer knows exactly when it must re-validate.

PATCH x.y.Z

Editorial fixes, clarified help text, corrected typos. No change to fields, types, validation, or flow semantics.

MINOR x.Y.z

Backward-compatible additions: a new optional field, a new enum value, a new step that does not alter existing required inputs.

MAJOR X.y.z

Backward-incompatible change: a field removed or made required, a type or validation tightened, a flow change that invalidates previously-valid inputs. A consumer that validated user data against an earlier version MUST re-validate when the document advances to a higher MAJOR.

Scope, at a glance

Each tier's mark nests inside the next — MAJOR carries everything MINOR and PATCH do, plus a breaking change.

  1. PATCH — no re-validation needed
  2. MINOR — safe to keep validating
  3. MAJOR — re-validate required

Published versions are immutable

A published (id, version) pair is immutable: its content never changes in place. Corrections ship as a new version, and superseded versions are retained for reproducibility. This is what lets a consumer pin to a version and trust that it will not shift underneath them.