DOCUMENTATION

Introduction

The shortest path into the standard: fetch a published schema, validate it, and read its verification record. Then the core concepts and the document envelope every conforming document shares.

Quickstart

This is the shortest path from finding GovSchema to holding a schema you can trust: fetch a published document from the registry, validate it against the format's meta-schema, then read its verification record before you rely on it. Every command below runs today against govschema.org and returns a real result. Each schema and the meta-schema are also mirrored, byte-for-byte, in the public source repository, hellogov-ai/govschema, which is where to open a pull request against them.

1. Fetch a published schema. Every conforming schema is a single JSON document. Here is the U.S. passport renewal (DS-82) reference, the same document behind the worked example:

bash Fetch the DS-82 reference schema 
curl -sSL https://govschema.org/registry/us/dos/passport-renewal-ds82/2.0.0/schema.json

2. Validate it against the meta-schema. Every document names the format version it conforms to in its $schema key, a resolvable govschema.org URL. Fetch that meta-schema and check the document against it with any JSON Schema (draft 2020-12) validator, such as ajv in Node:

javascript Validate the document with Node and ajv 
// npm i ajv ajv-formats
import Ajv2020 from "ajv/dist/2020.js";
import addFormats from "ajv-formats";

const url = "https://govschema.org/registry/us/dos/passport-renewal-ds82/2.0.0/schema.json";
const doc = await (await fetch(url)).json();
const metaSchema = await (await fetch(doc.$schema)).json();

const ajv = addFormats(new Ajv2020({ strict: false }));
console.log(ajv.validate(metaSchema, doc) ? "valid" : ajv.errors);
// → valid

3. Read the verification record before you trust it. A document passing validation only means it is structurally well-formed, not that it still matches the live government source. Every schema carries a verification object stating what has and hasn't been checked, by whom, and when it is next due for review:

json The verification record on the DS-82 schema 
"verification": {
  "method": "manual-source-review-v1",
  "lastVerifiedAt": "2026-06-30",
  "verifiedBy": "GovSchema Engineering",
  "nextReviewBy": "2026-12-30",
  "notes": "Source-derived reference; eligibility confirmed against the source, applicant fields not yet independently re-verified item-by-item. Status remains 'draft'."
}

Validation confirms structure, not liveness

A green validation result tells you a document conforms to the GovSchema format. It does not tell you the schema still matches the live government form today; only the verification record and its stated method do. Treat verification as the load-bearing check. See Verification for how records are produced and what each status means.

Core concepts

A GovSchema document is a versioned, machine-readable definition of a single government form or process. It is consumed by agent developers: it lets an agent know what a process requires before interacting with it, validate user-supplied data locally, and present an accurate, plain-language view to the person the agent acts for.

Every document is built on four commitments from the specification. Provenance is mandatory: a field that cannot be traced to a government source is not a standard, so every document cites exactly one authoritative source. Verification is first-class: every document carries an explicit verification record and a lifecycle status. Two audiences are served: machine identifiers are stable and terse, while human-facing text is plain language. Jurisdiction-neutral by construction: no structure privileges any one country, and encodings use international standards such as ISO 3166.

GovSchema is not an agent, is not a government system, and is not authoritative over the government source. The live government source is always authoritative; a GovSchema document is a description of it, and its accuracy is asserted only through the verification record.

The document envelope

Beyond the form-specific fields it describes, every conforming GovSchema document is a single JSON object carrying a common envelope of members so agents can identify, pin, trace, and trust it. These are the principal top-level members defined by the specification; the full list is on the schema-format page.

  • $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 (GSID) naming the process across all of its versions: a lowercase, slash-delimited registry path.

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

    Semantic version of this document's content. Consumers pin to a version; a published (id, version) is immutable.

    SemVer 2.0.0
  • status enum required

    Lifecycle status of the document.

    draft | verified | deprecated
  • title string required

    Human-readable process title, written in plain language.

  • jurisdiction object required

    The government jurisdiction this document describes: country (ISO 3166-1 alpha-2, uppercase) and level, with optional subdivision (ISO 3166-2).

  • authority object required

    The issuing government body: its official name, optional abbreviation, and homepage.

  • source object required

    Provenance: the authoritative government URL the document is derived from, the date it was retrieved, and an optional official form reference (documentRef).

  • verification object required

    Verification record: the method used and the date last verified against the source, with optional next-review date and notes.

  • fields array required

    The field definitions the form collects, each with a machine name, plain-language label, type, and validation constraints.

  • steps array optional

    Optional ordered description of the process flow: each step names the fields it collects and points to the next. A document without steps is a flat form presented in field order.

  • process object optional

    Process metadata: the process type and the source form's language (BCP 47 tag).

Worked example

The U.S. passport renewal (DS-82) schema reference shows the full page pattern for a single, real process: its identity and version, its field reference, the raw schema document, and its verification record. It is published in the registry at registry/us/dos/passport-renewal-ds82/.