SPECIFICATION · DRAFT v0.3

Schema format

A GovSchema document is a single JSON object describing one government form or process. This page summarizes the document model; the normative definition is the JSON Schema meta-schema, and where this prose and the meta-schema disagree, the meta-schema governs.

One document, one process

Each document captures four things about a single process: the fields an applicant must supply, with their types and validation rules; the flow, when the process has ordered or conditional steps; the provenance, naming the government source it was derived from and when; and the verification state, recording how and when it was confirmed against the live source.

A v0.1 document is strict and small: a closed core that producers can commit to, with richer constructs tracked as proposals and added in later spec versions rather than smuggled in as unrecognized members. Field-level validation reuses a constrained subset of JSON Schema 2020-12, so the format interoperates with the existing validator ecosystem rather than inventing new keywords.

Top-level members

The document object has the members below. Required members must be present in every conforming document; optional members are added when the process calls for them.

  • $schema string required

    URI of the GovSchema meta-schema this document conforms to.

    const: https://govschema.org/spec/v0.1/govschema.schema.json
  • govschemaVersion string required

    Version of the GovSchema specification this document targets.

    SemVer — e.g. 0.1.0
  • id string required

    Registry identifier, equal to the document's path under registry/ excluding the version.

    pattern: ^[a-z]{2}(/[a-z0-9-]+){2,}$
  • version string required

    SemVer version of this document's content.

    SemVer 2.0.0
  • title string required

    Human-readable process title.

  • description string optional

    Plain-language summary of the process.

  • status enum required

    Lifecycle status.

    draft | verified | deprecated
  • jurisdiction object required

    country (ISO 3166-1 alpha-2, uppercase) and level; optional subdivision (ISO 3166-2).

  • authority object required

    Issuing government body: name, optional abbreviation and url.

  • process object optional

    Process metadata: type and source-form language (BCP 47).

  • source object required

    Provenance: authoritative url, retrievedAt date, optional documentRef (official form number).

  • verification object required

    Record of how and when the schema was confirmed against the source: method, lastVerifiedAt.

  • license string optional

    SPDX or Creative Commons identifier the schema content is published under.

  • fields array required

    Field definitions (see Field types & validation).

  • steps array optional

    Optional ordered description of the process flow.

json Document envelope — excerpt from the US passport renewal (DS-82) reference schema 
{
  "$schema": "https://govschema.org/spec/v0.1/govschema.schema.json",
  "govschemaVersion": "0.1.0",
  "id": "us/dos/passport-renewal-ds82",
  "version": "1.0.0",
  "title": "United States Passport Renewal by Mail (Form DS-82)",
  "status": "draft",
  "jurisdiction": { "country": "US", "level": "national" },
  "authority": {
    "name": "U.S. Department of State, Bureau of Consular Affairs",
    "abbreviation": "DOS",
    "url": "https://travel.state.gov/"
  },
  "source": {
    "url": "https://travel.state.gov/en/passports/renew-replace/mail.html",
    "retrievedAt": "2026-06-30",
    "documentRef": "DS-82"
  },
  "verification": { "method": "manual-source-review-v1", "lastVerifiedAt": "2026-06-30" },
  "fields": [ /* … */ ],
  "steps": [ /* … */ ]
}

Normative source

This page is a summary. The normative shape of a GovSchema document is the JSON Schema meta-schema published with the specification; the prose specification explains and constrains it. A reference validation tool checks both the meta-schema and the requirements that cannot be expressed in JSON Schema.