SPECIFICATION

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.