SPECIFICATION · DRAFT v0.3

Field types & validation

The fields array is the heart of a schema: each field carries a stable machine name, a plain-language label as it appears on the source form, a type, and optional validation constraints. Field order is the default presentation order when a document has no steps.

Field definition members

Each field is an object with these members. The two-audience rule applies: name is the stable machine key, while label and description are plain language for the person the agent acts for.

  • name string required

    Machine key for the field, unique among its siblings.

    pattern: ^[a-z][a-zA-Z0-9_]*$
  • label string required

    Plain-language label as it appears on the source form.

  • type enum required

    One of the GovSchema field types listed below.

  • required boolean optional

    Whether a value must be supplied. Default false.

  • description string optional

    Longer plain-language guidance for the person completing the field.

  • sourceRef string optional

    Field-level provenance: where this field appears on the live form (e.g. "Section 2, Box 4a").

  • validation object optional

    Validation constraints, drawn from the constrained JSON Schema subset below. Enumerated values are listed in validation.enum.

Supported types

A field's type fixes the JSON value it carries and the constraints that may apply to it. v0.1 defines exactly these eight types.

  • string JSON string

    Free text. Constrain with minLength, maxLength, or pattern.

  • number JSON number

    Real number. Constrain with minimum / maximum.

  • integer JSON integer

    Whole number. Constrain with minimum / maximum.

  • boolean JSON boolean

    Yes / no.

  • date JSON string

    Full date, YYYY-MM-DD (RFC 3339 full-date).

  • enum JSON string

    One of a fixed set of string values, listed in validation.enum.

  • file JSON object

    A document upload described by metadata, never its bytes.

  • object JSON object

    A composite JSON object value.

Constraints

validation uses a deliberately small subset of JSON Schema 2020-12 validation keywords, so existing validators can be reused. v0.1 permits exactly: pattern, minLength, and maxLength for strings; minimum and maximum for numbers and integers; and enum for a fixed set of allowed values. No other keywords are recognised in v0.1.

A field whose type is enum lists its allowed string values in validation.enum. The subset is intentionally minimal for the draft; richer constraints are a candidate for a future minor version of the specification.

json An enum field — from the DS-82 schema 
{
  "name": "sexMarker",
  "label": "Sex marker to appear on the passport",
  "type": "enum",
  "required": true,
  "sourceRef": "DS-82 — Sex",
  "validation": { "enum": ["F", "M", "X"] }
}

Enumerated values and file fields

When type is enum, the field's validation.enum is a non-empty array of the allowed string values — the machine tokens a consumer may submit. The field's label describes the field; v0.1 does not carry a separate display label per value, so a consumer presents the values directly. Values are unique within the field.

A file field's value is metadata describing an upload, not the bytes — GovSchema never transports file contents. v0.1 does not define file-specific validation keywords such as maximum size or accepted media types; richer file constraints are a candidate for a future minor version of the specification.