DOCUMENTATION · DRAFT v0.3

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 — the place 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 — here, ajv in Node:

javascript Validate the document — Node + 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, not validation. 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, never a footnote. 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/.