FORMSPEC v1.0 — A JSON-Native Declarative Form Standard

Version: 1.0.0-draft.1
Date: 2025-07-10
Editors: Formspec Working Group

Abstract

Formspec is a format-agnostic, JSON-native standard for declarative form definition and validation. It specifies how to describe form fields, computed values, validation rules, conditional logic, repeatable sections, versioning, and structured validation results — independent of any rendering technology, programming language, or data transport mechanism. A Formspec definition is a self-contained JSON document that completely describes the structure, behavior, and constraints of a data-collection instrument without prescribing how that instrument is presented to a user. The standard draws on two decades of prior art — W3C XForms for its model/view/instance separation and reactive processing model, W3C SHACL for its composable validation shapes and structured result vocabulary, and HL7 FHIR R5 Questionnaire for its pragmatic approach to form hierarchy and response capture — and synthesizes these ideas into a coherent, JSON-first specification suitable for web, mobile, server-side, and offline implementations.

Status of This Document

This document is a draft specification. It has not been submitted to any standards body. The interfaces described herein are subject to change without notice. Implementors are encouraged to experiment with this specification and provide feedback, but MUST NOT treat it as stable for production use until a 1.0.0 release is published.

Conventions and Terminology

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in BCP 14 [RFC 2119] [RFC 8174] when, and only when, they appear in ALL CAPITALS, as shown here.

JSON syntax and data types are as defined in [RFC 8259]. JSON Pointer syntax is as defined in [RFC 6901]. URI syntax is as defined in [RFC 3986].

The following terms are used throughout this specification:

• Conformant processor — Any software that reads, writes, evaluates, or validates Formspec documents in accordance with this specification.
• Definition document — A JSON document conforming to the Formspec Definition schema.
• Normative — Text that forms part of the specification’s requirements.
• Informative — Text provided for explanation only; it does not impose requirements.

1. Introduction

1.1 Motivation

In 2003, the W3C published XForms 1.0, a declarative form standard that cleanly separated data model, validation logic, and presentation. XForms introduced concepts that remain unsurpassed in rigor: a reactive dependency graph for computed values, model-level validation independent of UI, the rebuild/recalculate/revalidate/refresh processing model, and the ability to define a form’s complete behavior in markup rather than imperative code.

XForms solved the right problems. But it solved them in XML, for XML, using XPath, within XHTML — a technology stack that the mainstream web ecosystem has largely moved away from. Today, JSON is the dominant data interchange format for web APIs, mobile applications, and cloud services. The form libraries that serve this ecosystem — JSON Schema-based generators, React form builders, low-code platform engines — each reinvent fragments of what XForms provided, but none offer a coherent, transport-independent, renderer-agnostic standard.

The result is a fragmented landscape:

• JSON Schema describes data shape but not computed fields, conditional visibility, or repeatable-section semantics.
• React Hook Form, Formik, and similar libraries bind validation to a specific JavaScript framework and runtime.
• Low-code platform schemas (Typeform, JotForm, Google Forms) are proprietary and tightly coupled to their rendering engines.
• FHIR Questionnaire provides a health-care-domain form model but lacks a general-purpose expression language and composable validation.
• ODK XForms extends XForms for mobile data collection but remains XML/XPath-dependent.

No existing specification provides “XForms for JSON” — a single, open, JSON-native standard that covers form structure, reactive behavior, composable validation, and structured results, while remaining independent of rendering technology and programming language.

Formspec fills this gap.

1.2 Design Principles

The following principles guided every design decision in this specification. They are listed in priority order; when principles conflict, higher-numbered principles yield to lower-numbered ones.

1.3 Scope

This specification defines:

• The JSON schema for Definition documents (form definitions).
• The JSON schema for Response documents (form responses).
• The Formspec Expression Language (FEL) grammar, type system, and built-in function library.
• The processing model (rebuild, recalculate, revalidate, notify).
• The validation result structure.
• Extension point contracts.

This specification does not define:

• Rendering, layout, widget selection, or visual style.
• Transport protocols (HTTP, WebSocket, message queue).
• Authentication or authorization.
• Storage or persistence mechanisms.
• A canonical serialization for non-JSON formats (YAML, CBOR, MessagePack), although such serializations MAY be defined in companion specifications.

1.4 Conformance

Formspec defines two conformance tiers.

1.4.1 Formspec Core

A conformant Core processor MUST:

1. Parse and validate any FormDefinition document that conforms to the Formspec JSON schema without error.
2. Support all core data types (§4.2.3), including money.
3. Implement all five Bind MIPs: calculate, relevant, required, readonly, constraint.
4. Implement the full FEL expression language (§3), including all built-in functions.
5. Implement validation shapes with severity levels and ValidationReport generation (§5).
6. Implement the four-phase processing model (§2.4).
7. Implement canonical identity, versioning, and response pinning (§6).
8. Support named option sets (§4.6).
9. Reject Definition documents containing circular dependencies with a diagnostic message identifying at least one cycle.

A Core processor MAY support a subset of FEL built-in functions, provided it signals an unsupported-function error when encountering a function it does not implement, rather than silently ignoring the call.

1.4.2 Formspec Extended

A conformant Extended processor MUST support Formspec Core plus:

1. Extension properties (§8).
2. Screener routing (§4.7).
3. Modular composition and assembly (§6.6).
4. Version migration maps (§6.7).
5. Pre-population declarations (§4.2.3, prePopulate).

A processor claiming Extended conformance implicitly claims Core conformance.

1.4.3 Conformance Prohibitions

A conformant Formspec processor (Core or Extended) MUST NOT:

1. Silently substitute definition versions. When validating a Response pinned to version X, the processor MUST use version X. If version X is unavailable, the processor MUST report an error.
2. Produce validation results for non-relevant fields. Non-relevant fields are exempt from all validation (§5.6 rule 1).
3. Block data persistence based on validation state. Validation and persistence are independent operations (§5.5).

2. Conceptual Model

2.1 Core Abstractions

Formspec is organized around six core abstractions. Each abstraction has a precise role; understanding these roles is a prerequisite for reading the rest of this specification.

2.1.1 Definition

A Definition is the complete, versioned specification of a form. It is a JSON document that contains:

• Identity — a canonical URL and a semantic version string that together form a globally unique, immutable reference.
• Items — the structural tree of fields, groups, and display nodes (§2.1.3).
• Binds — behavioral declarations that attach reactive expressions to data nodes (§2.1.4).
• Data Sources — declarations of secondary instances and external lookup tables (§2.1.2).
• Validation Shapes — composable constraint rule sets (§2.1.5).
• Metadata — human-readable title, description, authoring timestamps, and status.

A Definition is analogous to an XForms <model> combined with an XForms <body> structure declaration, or to a FHIR R5 Questionnaire resource.

A Definition MUST include a url (canonical URL) and a version (semantic version). The tuple (url, version) uniquely identifies a Definition across all systems. A conformant processor MUST treat two Definitions with the same (url, version) as identical.

Example. A minimal Definition:

{
  "formspec": "1.0",
  "url": "https://example.org/forms/intake",
  "version": "2.1.0",
  "title": "Patient Intake Form",
  "status": "active",
  "items": [
    { "key": "firstName", "type": "field", "dataType": "string" },
    { "key": "lastName",  "type": "field", "dataType": "string" }
  ]
}

2.1.2 Instance

An Instance is a JSON object whose structure mirrors the Definition’s item tree. It contains the current values for all fields. An Instance is the data substrate on which Binds operate, Shapes validate, and Responses persist.

Formspec supports multiple named instances:

A conformant processor MUST maintain the primary instance. It SHOULD support at least one secondary instance. It MAY support an arbitrary number.

An Instance mirrors the Item tree according to these rules:

• A field Item with key k corresponds to a JSON property k whose value is of the field’s declared dataType (or null if absent).
• A group Item with key k that is not repeatable corresponds to a JSON object under property k.
• A group Item with key k that is repeatable (repeat: true) corresponds to a JSON array under property k, where each element is a JSON object.
• A display Item has no representation in the Instance.

Example. Given this Item tree:

[
  { "key": "name", "type": "field", "dataType": "string" },
  { "key": "addresses", "type": "group", "repeatable": true, "children": [
      { "key": "street", "type": "field", "dataType": "string" },
      { "key": "city",   "type": "field", "dataType": "string" }
  ]}
]

A valid Instance would be:

{
  "name": "Ada Lovelace",
  "addresses": [
    { "street": "123 Analytical Engine Ln", "city": "London" },
    { "street": "456 Difference Row",       "city": "Bath" }
  ]
}

2.1.3 Item

An Item is a node in the Definition’s structural tree. Every Item MUST have a key property — a stable, machine-readable identifier that is unique among its siblings. The key is used in Instance paths, Bind targets, Shape targets, and FEL field references. A key MUST match the regular expression ^[a-zA-Z_][a-zA-Z0-9_]*$.

An Item MUST have a type property with one of three values:

Field items MUST declare a dataType from the following set:

Additional data type semantics MAY be layered onto core dataType values via the item-level extensions object (§7, §8.1).

Example. A group with mixed item types:

{
  "key": "demographics",
  "type": "group",
  "label": "Demographics",
  "children": [
    { "key": "heading", "type": "display", "label": "Demographics" },
    { "key": "dob",     "type": "field",   "dataType": "date",
      "label": "Date of Birth" },
    { "key": "sex",     "type": "field",   "dataType": "choice",
      "label": "Sex at Birth",
      "options": [
        { "value": "M", "label": "Male" },
        { "value": "F", "label": "Female" },
        { "value": "O", "label": "Other" }
      ]
    }
  ]
}

2.1.4 Bind

A Bind is a behavioral declaration attached to one or more data nodes by path. Binds are the bridge between the structural layer (Items) and the behavioral layer (reactive expressions). A Bind is not a visual concept; it exists purely in the data/logic domain.

Each Bind MUST specify a path — a path expression (using dot-separated key notation) that identifies the data node(s) to which the Bind applies. A Bind MAY specify one or more of the following properties, each containing a FEL expression:

Binds are evaluated reactively. When a value in the Instance changes, the processor MUST re-evaluate all Binds whose expressions reference the changed value, directly or transitively, following the processing model (§2.4).

Example. Binds for a tax form:

{
  "binds": [
    {
      "path": "totalIncome",
      "calculate": "$wages + $interest + $dividends"
    },
    {
      "path": "spouseInfo",
      "relevant": "$filingStatus = 'married'"
    },
    {
      "path": "ssn",
      "required": "true",
      "constraint": "matches($ssn, '^[0-9]{3}-[0-9]{2}-[0-9]{4}$')",
      "constraintMessage": "SSN must be in the format 000-00-0000."
    },
    {
      "path": "filingDate",
      "default": "today()"
    }
  ]
}

2.1.5 Validation Shape

A Validation Shape is a named, composable validation rule set. The concept is borrowed from W3C SHACL (Shapes Constraint Language) and adapted for Formspec’s JSON-native context.

Each Shape MUST have:

• An id — a unique identifier within the Definition.
• A target — a data path, or the special root path "#", to which the Shape applies.
• A message — a human-readable description of the violation.
• Either a constraint expression (FEL, returning boolean) or a composition over other Shapes.
• Optional severity, code, activeWhen, and timing properties controlling how and when the Shape fires.

Shapes MAY compose with other Shapes using the following logical operators:

Shapes produce ValidationResult entries. A ValidationResult is a structured JSON object, not a boolean flag. Each result entry includes the Shape id, target path, severity, message, code, and the evaluated expression. This structured output supports accessibility tooling, multi-level review workflows, and machine-to-machine validation pipelines.

Example. A composable validation shape:

{
  "shapes": [
    {
      "id": "dateRangeValid",
      "target": "endDate",
      "severity": "error",
      "constraint": "$endDate >= $startDate",
      "message": "End date must not precede start date.",
      "code": "DATE_RANGE_001"
    },
    {
      "id": "dateRangeReasonable",
      "target": "endDate",
      "severity": "warning",
      "constraint": "dateDiff($endDate, $startDate, 'days') <= 365",
      "message": "Date range exceeds one year. Please verify.",
      "code": "DATE_RANGE_002"
    },
    {
      "id": "dateRangeComplete",
      "target": "endDate",
      "message": "Date range validation failed.",
      "and": ["dateRangeValid", "dateRangeReasonable"]
    }
  ]
}

2.1.6 Response

A Response is a completed or in-progress Instance pinned to a specific Definition version. It is the unit of data capture — the filled-in form.

The canonical structural contract for Response properties is generated from schemas/response.schema.json:

The generated table above defines required and optional properties. In this spec section, prose requirements describe semantics that the schema alone cannot express.

A Response references exactly one Definition by the tuple (definitionUrl, definitionVersion). A conformant processor MUST reject a Response whose definitionVersion does not match any known Definition at the given definitionUrl.

Example. A completed Response:

{
  "definitionUrl": "https://example.org/forms/intake",
  "definitionVersion": "2.1.0",
  "status": "completed",
  "authored": "2025-07-10T14:30:00Z",
  "author": { "id": "user-42", "name": "Dr. Grace Hopper" },
  "data": {
    "firstName": "Ada",
    "lastName": "Lovelace"
  }
}

2.1.7 Data Source

A Data Source is a declaration within a Definition that makes external or supplemental data available to FEL expressions at runtime. Data Sources are the mechanism by which secondary instances (§2.1.2) are populated.

Each Data Source MUST have a name (string, unique identifier within the Definition, used in @instance('name') references, MUST match ^[a-zA-Z_][a-zA-Z0-9_]*$).

Each Data Source MUST also declare its content via one of the following mechanisms:

A Data Source MAY include a schema property describing the expected shape of the data (field names and types). This schema is informative — it aids tooling and documentation — but a conformant processor is NOT REQUIRED to validate Data Source contents against it.

Secondary instances populated by Data Sources are read-only during form completion. A calculate Bind MUST NOT target a path within a secondary instance. A conformant processor MUST signal a definition error if such a Bind is encountered.

Example. Data source declarations:

{
  "dataSources": [
    {
      "name": "countryCodes",
      "data": [
        { "code": "US", "label": "United States" },
        { "code": "GB", "label": "United Kingdom" },
        { "code": "CA", "label": "Canada" }
      ]
    },
    {
      "name": "priorYear",
      "source": "https://api.example.org/responses/2024/{{respondentId}}"
    },
    {
      "name": "inventory",
      "source": "formspec-fn:loadInventoryData"
    }
  ]
}

These data sources are then referenced in FEL expressions:

@instance('priorYear').totalIncome
@instance('countryCodes')  

2.2 Relationships

The six core abstractions relate to each other as follows. A conformant processor MUST maintain these relationships.

┌────────────────────────────────────────────────────────────────┐
│                         Definition                         │
│  (url + version = unique identity)                         │
│                                                            │
│  ┌────────────┐  ┌──────────┐  ┌────────────┐  ┌────────────┐  │
│  │ Items      │  │ Binds    │  │ Shapes     │  │ Data       │  │
│  │ (tree)     │  │ (list)   │  │ (list)     │  │ Sources    │  │
│  └──────┬─────┘  └────┬─────┘  └─────┬──────┘  └────────────┘  │
│       │             │             │                            │
└───────┼─────────────┼─────────────┼────────────────────────────┘
       │             │             │
       │    target    │    target   │
       │   (by path)  │  (by path)  │
       ▼             ▼             ▼
┌─────────────────────────────────────────┐
│        Instance (JSON object)          │
│  Mirrors Item tree structure.          │
│  Contains current field values.        │
└───────────────────┬─────────────────────┘
                    │
                    │ contained in
                    ▼
┌─────────────────────────────────────────┐
│          Response                      │
│  references Definition (url+version)   │
│  contains Instance (data)              │
│  carries metadata (who, when, status)  │
└─────────────────────────────────────────┘

Formal relationship constraints:

1. A Definition MUST contain one or more Items. Items form a tree (a single root list of Items, each of which may have children).
2. A Definition MAY contain zero or more Binds. Each Bind MUST reference at least one Item by path. A conformant processor MUST signal an error if a Bind’s target does not resolve to any Item in the Definition.
3. A Definition MAY contain zero or more Validation Shapes. Each Shape MUST reference at least one Item by path.
4. A Response MUST reference exactly one Definition by the tuple (definitionUrl, definitionVersion).
5. A Response contains exactly one primary Instance. The Instance’s structure MUST conform to the Definition’s Item tree.
6. Binds and Shapes operate on Instance data. They reference Items by path, and those paths resolve to nodes in the Instance.

2.3 The Three Layers

Formspec enforces a strict three-layer separation of concerns. This separation is not a suggestion — it is an architectural invariant.

Layer 1: Structure Layer (Items)

The Structure Layer answers the question: WHAT data is collected?

This layer defines:

• The hierarchical tree of fields, groups, and display nodes.
• Each field’s data type.
• Which groups are repeatable.
• The set of valid options for choice fields.
• Labels and help text (as human-readable metadata, not rendering instructions).

The Structure Layer is a pure schema. It contains no logic, no expressions, and no conditional behavior. A Definition consisting only of a Structure Layer is valid — it describes a simple, static form.

Layer 2: Behavior Layer (Binds + Shapes)

The Behavior Layer answers the question: HOW does data behave?

This layer defines:

• Computed values (calculate Binds).
• Conditional visibility (relevant Binds).
• Dynamic required/read-only state (required, readonly Binds).
• Per-field constraints (constraint Binds).
• Cross-field and cross-section validation (Shapes).
• Default values (default Binds).

All behavior is expressed in FEL (§3). The Behavior Layer is reactive: when data changes, affected expressions are re-evaluated automatically.

The Behavior Layer MUST NOT contain any rendering instructions, layout directives, widget specifications, or style information. It operates entirely in the data/logic domain.

Layer 3: Presentation Layer

The Presentation Layer answers the question: HOW is data displayed?

This specification provides OPTIONAL presentation hints — advisory metadata that helps renderers make informed decisions about widget selection, layout, and accessibility. Presentation hints are defined in §4.2.5 (per-item) and §4.1.1 (form-wide).

Presentation hints are strictly advisory:

• A conforming processor MAY ignore any or all presentation hints.
• A conforming definition MUST NOT require presentation hints for correct data capture, validation, or submission.
• Hints MUST NOT alter data semantics, validation results, or processing behavior.

The following remain out of scope and are NOT defined by this specification:

• Rendering engines, widget toolkits, or CSS.
• Platform-specific affordances (touch targets, screen reader APIs).
• Navigation and focus management.
• Visual style, themes, and branding.

The Formspec Theme Specification defines sidecar theme documents that override Tier 1 presentation hints with a selector cascade, design tokens, widget configurations, and page layout. Companion specifications MAY standardize additional Presentation Layer schemas (e.g., component models). Such specifications are independent of this document.

This separation ensures that a single Definition can drive a web form, a mobile form, a PDF rendering, a voice-guided form, and an API-only validation endpoint — all without modification.

2.4 Processing Model

Formspec defines a four-phase processing cycle, adapted from the XForms processing model, that governs how changes in Instance data propagate through Binds and Shapes. A conformant processor MUST implement these four phases and MUST execute them in the specified order.

Phase 1: Rebuild

Trigger: The structural shape of the Instance has changed — specifically, a repeat instance has been added or removed, or the Definition itself has been replaced (e.g., version migration).

Action: The processor MUST:

1. Re-index all Items, updating path-to-node mappings for any repeat instances.
2. Reconstruct the dependency graph. The dependency graph is a directed acyclic graph (DAG) where each node is a Bind or Shape expression and each edge represents a field reference within that expression. New repeat instances introduce new nodes; removed repeat instances remove nodes.
3. Validate that the dependency graph remains acyclic. If a cycle is detected, the processor MUST signal a definition error and MUST NOT proceed to Phase 2.

Postcondition: The dependency graph accurately reflects the current structure of the Instance.

Informative note: For Definitions with no repeatable groups, the Rebuild phase is a no-op after initial load. Processors MAY optimize accordingly.

Phase 2: Recalculate

Trigger: One or more field values in the Instance have changed (via user input, programmatic update, or a prior Recalculate pass), or Phase 1 has completed.

Action: The processor MUST:

1. Identify the set of dirty nodes — fields whose values have changed since the last Recalculate.
2. Compute the affected subgraph — the transitive closure of all nodes reachable from the dirty nodes in the dependency graph.
3. Topologically sort the affected subgraph.
4. Evaluate each Bind expression in topological order:
   • calculate — Compute the value and write it to the Instance. If the computed value differs from the current value, mark the target node as dirty (which may expand the affected subgraph; the processor MUST iterate until no new dirty nodes are produced, up to a processor-defined limit of at least 100 iterations).
   • relevant — Evaluate and store the boolean result. If a node transitions from relevant to non-relevant, the processor MUST mark all descendant nodes as non-relevant. If a node transitions from non-relevant to relevant, the processor MUST re-evaluate all descendant Binds.
   • required — Evaluate and store the boolean result.
   • readonly — Evaluate and store the boolean result.

Postcondition: All calculate, relevant, required, and readonly Bind states are consistent with current Instance data. The Instance contains no stale computed values.

Minimal recalculation: A conformant processor MUST NOT re-evaluate Bind expressions that are not in the affected subgraph. This is the minimal recalculation guarantee, borrowed from XForms.

Phase 3: Revalidate

Trigger: Phase 2 has completed.

Action: The processor MUST:

1. For each relevant field that is in the affected subgraph or whose required / relevant state changed in Phase 2:
   1. If the field has a constraint Bind, evaluate the constraint expression. If the result is false, record a ValidationResult with severity "error" and the Bind’s constraintMessage.
   2. If the field has a required Bind that evaluated to true, and the field’s value is empty (null, empty string "", or empty array []), record a ValidationResult with severity "error" and a processor-generated message (or the Bind’s requiredMessage, if provided).
2. For each Validation Shape whose target paths intersect the affected subgraph, evaluate the Shape’s constraint expressions and record ValidationResult entries for any failures.
3. Composed Shapes (and, or, not, xone) MUST be evaluated by evaluating their constituent Shapes and combining results according to the composition operator.

Postcondition: A complete, current set of ValidationResult entries exists for all affected nodes.

Phase 4: Notify

Trigger: Phase 3 has completed.

Action: The processor MUST signal state changes to any attached Presentation Layer or observer. The notification mechanism is implementation-defined, but MUST convey at minimum:

• The set of fields whose values changed.
• The set of fields whose relevant, required, or readonly state changed.
• The set of fields whose validation state changed (new errors, resolved errors, new warnings).

A Presentation Layer receiving these notifications can update the display accordingly. The Formspec specification does not prescribe how notifications are delivered (events, callbacks, reactive signals, polling).

Deferred Processing

During batch operations — such as loading an entire Response, importing data from an external source, or programmatically setting multiple fields — the processor SHOULD defer the four-phase cycle until the batch completes. This avoids redundant intermediate evaluations.

Specifically, during a batch:

1. All field writes are accumulated.
2. No Rebuild, Recalculate, Revalidate, or Notify phases execute.
3. When the batch ends, the processor executes one complete four-phase cycle with the union of all dirty nodes.

A conformant processor MUST produce the same final state regardless of whether changes are processed individually or in a batch.

Presentation Hints and Processing

The presentation (§4.2.5) and formPresentation (§4.1.1) objects are metadata. They do NOT participate in the Rebuild → Recalculate → Revalidate → Notify processing cycle. FEL expressions MUST NOT reference presentation properties. When a processor serializes a Response, presentation properties MUST NOT appear in the Response data.

2.5 Validation Results

Validation in Formspec produces structured results, not boolean pass/fail flags. This section defines the ValidationResult data structure. Every conformant processor MUST produce ValidationResult entries conforming to this structure.

2.5.1 ValidationResult Entry

A single ValidationResult entry is a JSON object with the following properties:

Standard Built-in Constraint Codes:

The following codes are RESERVED. Conformant processors MUST use these exact codes for the corresponding built-in constraints. Shape-level and external codes override the generic defaults.

Example. A set of ValidationResult entries:

[
  {
    "severity": "error",
    "path": "ssn",
    "message": "SSN must be in the format 000-00-0000.",
    "code": "FORMAT_SSN",
    "source": "bind",
    "expression": "matches($ssn, '^[0-9]{3}-[0-9]{2}-[0-9]{4}$')"
  },
  {
    "severity": "warning",
    "path": "endDate",
    "message": "Date range exceeds one year. Please verify.",
    "code": "DATE_RANGE_002",
    "source": "shape",
    "shapeId": "dateRangeReasonable"
  },
  {
    "severity": "error",
    "path": "lineItems[2].quantity",
    "message": "This field is required.",
    "code": "REQUIRED",
    "source": "bind"
  }
]

2.5.2 Severity Levels

Formspec defines three severity levels. Severity levels are strictly ordered: error > warning > info.

A conformant processor MUST distinguish between the three severity levels in its result output. A processor MUST NOT collapse warning into error or omit info results without explicit user configuration.

2.5.3 Aggregated Validation State

The aggregated validation state of a Response is derived from its ValidationResult entries:

The aggregated state is a convenience derivation. A conformant processor MUST be able to report the aggregated state but MUST also provide access to the full list of individual ValidationResult entries.

2.5.4 Non-Relevant Fields

Fields that are non-relevant (i.e., whose relevant Bind evaluates to false) MUST NOT produce ValidationResult entries. If a field transitions from relevant to non-relevant during Recalculate, any previously-emitted ValidationResult entries for that field MUST be removed during Revalidate.

Conversely, when a field transitions from non-relevant to relevant, the processor MUST evaluate all applicable Binds and Shapes for that field during the next Revalidate phase.

3. Expression Language — Formspec Expression Language (FEL)

3.1 Design Goals

The Formspec Expression Language (FEL) is a small, deterministic, side-effect-free expression language designed for evaluating form logic. It is not a general-purpose programming language. It has no statements, no loops, no variable assignment, no I/O, and no user-defined functions (though extensions MAY register additional built-in functions).

FEL’s design goals are:

1. Host-language independence. FEL MUST be implementable in any general-purpose programming language. It MUST NOT depend on JavaScript semantics, XPath axes, Python operator overloading, or any other host-language feature.
2. Familiarity. FEL syntax is designed to be readable by spreadsheet users and web developers. Function names follow common conventions (e.g., sum(), if(), today()). Operators use standard mathematical notation.
3. Unambiguous grammar. FEL’s grammar is a Parsing Expression Grammar (PEG), which is unambiguous by construction. There is exactly one valid parse tree for any syntactically valid FEL expression.
4. Determinism. Given the same Instance data, a FEL expression MUST always produce the same result, regardless of implementation language or platform. The sole exception is now(), which returns the current date-time and is therefore non-deterministic by design; processors SHOULD document their now() resolution behavior.
5. Type safety. FEL uses a small, explicit type system. Type mismatches produce errors, not silent coercions. This prevents an entire class of bugs common in loosely typed expression languages.

3.2 Field References

FEL expressions operate on Instance data by referencing fields. A field reference resolves to the current value of a field in the Instance.

3.2.1 Simple References

The $ sigil introduces a field reference:

Field references are lexically scoped. When a reference appears inside a Bind targeting a field within a repeatable group, $siblingField resolves to the sibling field within the same repeat instance — not across all instances. This mirrors XForms scoping behavior.

3.2.2 Repeat References

Within repeatable contexts, additional reference forms are available:

A conformant processor MUST signal an error if an explicit index is out of bounds (less than 1 or greater than the number of repeat instances).

3.2.3 Cross-Instance References

To reference data in a secondary instance, use the @instance() accessor:

@instance('priorYear').totalIncome

The argument to @instance() MUST be a string literal matching the name of a declared data source in the Definition. If the named instance does not exist, the processor MUST signal an error.

Field paths after @instance() follow the same dot-notation as primary instance references.

Example. A calculation that compares current-year income to prior-year:

$totalIncome - @instance('priorYear').totalIncome

3.3 Operators

FEL defines the following operators, listed from lowest to highest precedence. Operators at the same precedence level are left-associative unless otherwise noted.

Precedence Table

Operator Semantics

Arithmetic operators (+, -, *, /, %):

• Both operands MUST be of type number. If either operand is not a number, the processor MUST signal a type error.
• Division by zero MUST signal an evaluation error (not produce Infinity or NaN).
• The % (modulo) operator returns the remainder of integer division. Both operands MUST be numbers; the result follows the sign of the dividend.

Comparison operators (<, >, <=, >=):

• Both operands MUST be of the same type: number compared with number, string compared with string (lexicographic, Unicode code-point order), date compared with date (chronological order).
• Comparing operands of different types MUST signal a type error, with one exception: comparing any value to null is permitted and is defined below.

Equality operators (=, !=):

• Any two values of the same type may be compared for equality.
• null = null evaluates to true.
• null = <any non-null value> evaluates to false.
• Cross-type equality (e.g., number = string) MUST signal a type error.

Logical operators (and, or, not):

• Operands MUST be of type boolean. Non-boolean operands MUST signal a type error (no truthy/falsy coercion).
• and and or use short-circuit evaluation: if the left operand of and is false, the right operand is not evaluated; if the left operand of or is true, the right operand is not evaluated.

String concatenation (&):

• Both operands MUST be of type string. Use string() to convert non-string values before concatenation.
• The & operator is used instead of + to prevent ambiguity between numeric addition and string concatenation.

Example: $firstName & ' ' & $lastName → "Ada Lovelace"

Null-coalescing operator (??):

• If the left operand is null, the result is the right operand. Otherwise, the result is the left operand.
• Both operands MUST be of the same type (or the left operand is null).

Example: $middleName ?? 'N/A' → "N/A" if middleName is null.

Membership operators (in, not in):

• The left operand is a scalar value. The right operand MUST be an array.
• value in array evaluates to true if the array contains an element equal to the value (using = semantics).
• value not in array is equivalent to not (value in array).

Example: $status in ['active', 'pending']

Ternary conditional (? :):

• Syntax: condition ? thenExpr : elseExpr
• condition MUST be of type boolean.
• If condition is true, the result is thenExpr; otherwise, elseExpr.
• Only the selected branch is evaluated.

3.4 Type System

FEL defines five primitive types and one compound type.

3.4.1 Primitive Types

Decimal precision rationale: The number type uses decimal (base-10) semantics rather than IEEE 754 binary floating-point. This ensures that 0.1 + 0.2 = 0.3 — a critical property for financial calculations. JSON serialization uses JSON number syntax per RFC 8259. Implementations SHOULD preserve the original decimal representation when round-tripping values through the Instance.

Money type: The amount field of a money value MUST be serialized as a JSON string containing a decimal number (not a JSON number) to preserve precision. currency is an ISO 4217 three-letter code. Processors that do not support the money type MUST fall back to treating the value as a JSON object with amount and currency string properties.

3.4.2 Compound Type

Array literals are supported in FEL:

['active', 'pending', 'review']
[1, 2, 3, 4, 5]

All elements of an array literal MUST be of the same type. A mixed-type array literal is a parse error.

3.4.3 Coercion Rules

FEL does not perform implicit type coercion. The following rules are normative:

1. Arithmetic operators (+, -, *, /, %) require both operands to be number. Applying an arithmetic operator to a non-number operand MUST signal a type error.
2. The concatenation operator (&) requires both operands to be string.
3. Logical operators (and, or, not) require boolean operands.
4. Comparison operators require both operands to be of the same type (or one to be null).
5. There is no “truthy” or “falsy” concept. The number 0 is not false; the empty string '' is not false; null is not false. Only the boolean value false is false.

Explicit coercion is performed via cast functions:

Critical distinction: Empty string and null are not the same.

• null means the value is absent — the field has never been set.
• '' (empty string) means the value is present but empty — the field was set to an empty string.

A required Bind treats both null and '' as unsatisfied (the field is not considered answered). But in all other contexts, null != ''.

3.5 Built-in Functions

The following functions are part of the core FEL specification. A conformant processor MUST implement all functions in this section. Extension functions (§7) MAY supplement but MUST NOT override these functions.

In the signatures below, T denotes any type, and ? after a parameter name indicates it is optional.

3.5.1 Aggregate Functions

Aggregate functions operate on arrays and reduce them to a single value.

Example. Compute a line-item total:

sum($lineItems[*].quantity * $lineItems[*].unitPrice)

Informative note: The above requires element-wise multiplication of two arrays. When two arrays of equal length are operands to an arithmetic operator, the operation is applied element-wise, producing a new array. If the arrays are of different lengths, the processor MUST signal an error.

3.5.2 String Functions

3.5.3 Numeric Functions

3.5.4 Date Functions

3.5.5 Logical Functions

3.5.6 Type-Checking Functions

3.5.7 Money Functions

3.5.8 MIP-State Query Functions

These functions query the current computed state of model item properties. They are evaluated during the Revalidate phase, after all Recalculate MIPs have been resolved.

The argument is a field reference using standard FEL $path syntax:

if(not(valid($ein)), "Please correct EIN before proceeding", "")

3.5.9 Repeat Navigation Functions

These functions navigate within repeat contexts. All MUST only be called within a repeat context; calling them outside a repeat is a definition error.

Usage:

prev().cumulative_total + @current.amount
parent().section_total

Dependency semantics: When row order changes (insert, delete, reorder), all expressions using prev() or next() in the affected repeat MUST be re-evaluated. Implementations SHOULD treat prev()/next() as depending on the entire repeat collection for dependency tracking purposes.

3.5.10 Locale, Runtime Metadata, and Instance Lookup

These functions support host-provided locale and metadata, programmatic access to secondary instance data, and plural selection aligned with Unicode CLDR cardinal plural rules.

3.6 Dependency Tracking

FEL expressions are the source of all reactive behavior in Formspec. To support minimal recalculation (§2.4, Phase 2), a conformant processor MUST implement dependency tracking as specified in this section.

3.6.1 Reference Extraction

When a Definition is loaded, the processor MUST parse every FEL expression in every Bind and Shape and extract the set of field references contained in that expression. A field reference is any syntactic construct that resolves to an Instance value:

• $fieldKey
• $parent.child
• $repeat[*].field
• $repeat[index].field
• @current.field
• @instance('name').field

The processor MUST build a dependency graph — a directed graph G = (V, E) where:

• Each vertex v ∈ V is a data node (a field in the Instance) or a Bind/Shape expression.
• Each edge (u, v) ∈ E means “the expression for v references the value of u.” In other words, v depends on u.

3.6.2 Topological Ordering

The dependency graph MUST be a directed acyclic graph (DAG). A conformant processor MUST verify acyclicity during the Rebuild phase (§2.4, Phase 1).

If a cycle is detected, the processor MUST:

1. Signal a definition error (not a runtime error).
2. Include in the error message the set of field keys that participate in at least one cycle.
3. Refuse to proceed with Recalculate, Revalidate, or Notify.

If the graph is acyclic, the processor MUST compute a topological ordering of the vertices. This ordering determines the evaluation sequence: a Bind’s expression is evaluated only after all expressions it depends on have been evaluated.

3.6.3 Incremental Re-evaluation

When a field value changes (due to user input or an external update), the processor MUST:

1. Identify the changed field as the root of the dirty subgraph.
2. Compute the affected set — all vertices reachable from the root by following dependency edges forward (i.e., all expressions that directly or transitively depend on the changed field).
3. Topologically sort the affected set.
4. Re-evaluate only the expressions in the affected set, in topological order.

Expressions outside the affected set MUST NOT be re-evaluated. This is the minimal recalculation guarantee.

Example. Consider three fields and two Binds:

• $price (user-entered)
• $quantity (user-entered)
• $subtotal with Bind: calculate = $price * $quantity
• $total with Bind: calculate = sum($lineItems[*].subtotal) + $tax

If the user changes $price, the affected set is {$subtotal, $total}. The processor re-evaluates $subtotal first (because $total depends on $subtotal), then $total. The field $quantity and any Binds that do not transitively depend on $price are untouched.

3.6.4 Wildcard Dependencies

A wildcard repeat reference ($repeat[*].field) introduces a dependency on every instance of field within the repeat. When any instance of that field changes, or when a repeat instance is added or removed, the expression containing the wildcard reference is in the affected set.

A conformant processor MUST track wildcard dependencies at the collection level: a change to any element of the collection marks the wildcard-dependent expression as dirty.

3.7 Grammar (Informative)

This section provides a simplified Parsing Expression Grammar (PEG) for FEL. It is informative, not normative — the normative semantics are defined in §§3.2–3.6 above. This grammar is provided to demonstrate that FEL is unambiguous and PEG-parseable, and to serve as a starting point for implementors.

The grammar uses the following PEG conventions:

• 'literal' — literal string match
• / — ordered choice
• * — zero or more
• + — one or more
• ? — optional
• ( ) — grouping
• ! — negative lookahead

# ============================================================
# Formspec Expression Language (FEL) — PEG Grammar (Informative)
# ============================================================

Expression     ← _ LetExpr _

LetExpr        ← 'let' _ Identifier _ '=' _ LetValue _ 'in' _ LetExpr
               / IfExpr

# LetValue omits Membership to disambiguate the 'in' keyword.
# Use parentheses for membership in let-value position: let x = (1 in $arr) in ...
LetValue       ← IfExpr   # with Membership production omitted from the chain

IfExpr         ← 'if' _ Ternary _ 'then' _ IfExpr _ 'else' _ IfExpr
               / Ternary

Ternary        ← LogicalOr (_ '?' _ Expression _ ':' _ Expression)?

LogicalOr      ← LogicalAnd (_ 'or' _ LogicalAnd)*

LogicalAnd     ← Equality (_ 'and' _ Equality)*

Equality       ← Comparison ((_ '=' / _ '!=') _ Comparison)*

Comparison     ← Membership ((_ '<=' / _ '>=' / _ '<' / _ '>') _ Membership)*

Membership     ← NullCoalesce ((_ 'not' _ 'in' / _ 'in') _ NullCoalesce)?

NullCoalesce   ← Addition (_ '??' _ Addition)*

Addition       ← Multiplication ((_ '+' / _ '-' / _ '&') _ Multiplication)*

Multiplication ← Unary ((_ '*' / _ '/' / _ '%') _ Unary)*

Unary          ← 'not' _ Unary
               / '-' _ Unary
               / Postfix

Postfix        ← Atom PathTail*

PathTail       ← '.' Identifier
               / '[' _ ( Integer / '*' ) _ ']'

Atom           ← IfCall
               / FunctionCall
               / FieldRef
               / ObjectLiteral
               / ArrayLiteral
               / Literal
               / '(' _ Expression _ ')'

IfCall         ← 'if' _ '(' _ ArgList? _ ')'

FieldRef       ← '$' Identifier PathTail*
               / '$'
               / '@' Identifier ('(' _ StringLiteral _ ')')? ('.' Identifier)*

FunctionCall   ← Identifier '(' _ ArgList? _ ')'
ArgList        ← Expression (_ ',' _ Expression)*

ObjectLiteral  ← '{' _ ObjectEntries? _ '}'
ObjectEntries  ← ObjectEntry (_ ',' _ ObjectEntry)*
ObjectEntry    ← (Identifier / StringLiteral) _ ':' _ Expression

ArrayLiteral   ← '[' _ (Expression (_ ',' _ Expression)*)? _ ']'

Literal        ← DateTimeLiteral
               / DateLiteral
               / NumberLiteral
               / StringLiteral
               / 'true'
               / 'false'
               / 'null'

DateLiteral     ← '@' [0-9]{4} '-' [0-9]{2} '-' [0-9]{2}
DateTimeLiteral ← '@' [0-9]{4} '-' [0-9]{2} '-' [0-9]{2} 'T'
                   [0-9]{2} ':' [0-9]{2} ':' [0-9]{2} ('Z' / [+-][0-9]{2}':'[0-9]{2})

# --- Lexical rules ---

Identifier     ← [a-zA-Z_] [a-zA-Z0-9_]*

NumberLiteral  ← '-'? [0-9]+ ('.' [0-9]+)? (('e' / 'E') ('+' / '-')? [0-9]+)?

StringLiteral  ← '\'' (!'\'' .)* '\''
               / '"' (!'"' .)* '"'

Integer        ← [0-9]+

_              ← [ \t\n\r]*              # Optional whitespace

Informative note: This grammar intentionally omits Unicode escape sequences in string literals, detailed whitespace rules, and comment syntax. The normative grammar is defined in the companion document FEL Normative Grammar v1.0.

3.8 Null Propagation

Null values require special handling in an expression language used for form logic. Fields are frequently null — a user has not yet filled in a value, a repeated section is empty, a secondary instance lookup returns no match. Formspec defines explicit null-propagation rules to avoid ambiguity.

3.8.1 General Rule

Unless otherwise specified by a specific function or operator, null propagates through expressions: if any operand to a function or operator is null, the result is null.

This rule applies to:

• Arithmetic operators: null + 5 → null, 10 * null → null.
• String concatenation: 'hello' & null → null.
• Comparison operators: null < 5 → null (not true or false).

When a null result reaches a context that requires a boolean — such as a relevant, required, constraint, or if() condition — the processor MUST treat null as follows:

3.8.2 Functions with Special Null Handling

The following functions define their own null behavior and do NOT follow the general propagation rule:

3.8.3 Missing Field References

If a FEL expression references a field key that exists in the Definition but has no value in the Instance (i.e., the JSON property is absent or explicitly null), the reference resolves to null.

If a FEL expression references a field key that does not exist in the Definition, the processor MUST signal a definition error at load time (not at evaluation time). This is a static check.

3.9 Element-Wise Array Operations

When an arithmetic, comparison, or string operator is applied to two arrays of equal length, the operation is performed element-wise, producing a new array of the same length.

Formal rules:

1. If both operands are arrays of equal length n, the result is an array of length n where element i is the result of applying the operator to element i of each operand.
2. If both operands are arrays of different lengths, the processor MUST signal an evaluation error.
3. If one operand is a scalar and the other is an array of length n, the scalar is broadcast: the result is an array of length n where each element is the result of applying the operator to the scalar and the corresponding array element.
4. Null elements within arrays follow the null-propagation rules (§3.8.1): an operation on a null element produces null in the corresponding position.

Element-wise operations are the primary mechanism for computing derived values across repeat collections before aggregation.

Example. Compute line-item totals and then sum them:

sum($lineItems[*].quantity * $lineItems[*].unitPrice)

If the Instance contains:

{
  "lineItems": [
    { "quantity": 2, "unitPrice": 10.00 },
    { "quantity": 5, "unitPrice": 3.50 },
    { "quantity": 1, "unitPrice": 25.00 }
  ]
}

Then $lineItems[*].quantity → [2, 5, 1] and $lineItems[*].unitPrice → [10.00, 3.50, 25.00].

Element-wise multiplication: [2, 5, 1] * [10.00, 3.50, 25.00] → [20.00, 17.50, 25.00].

sum([20.00, 17.50, 25.00]) → 62.50.

Example. Scalar broadcast — apply a tax rate to all line totals:

$lineItems[*].amount * $taxRate

If $taxRate is 0.08 and $lineItems[*].amount is [20.00, 17.50, 25.00], the result is [1.60, 1.40, 2.00].

3.10 Error Handling

FEL distinguishes between two classes of errors: definition errors (detected at load time) and evaluation errors (detected at runtime during expression evaluation).

3.10.1 Definition Errors

A definition error indicates that the Definition document is malformed or internally inconsistent. Definition errors are detected during the initial load and Rebuild phase. A conformant processor MUST detect all of the following and MUST NOT proceed to Recalculate:

3.10.2 Evaluation Errors

An evaluation error occurs during expression evaluation when operand values violate type or domain constraints. A conformant processor MUST handle evaluation errors as follows:

Design rationale: Evaluation errors produce null rather than halting evaluation because form users should not be punished for a Definition author’s mistake. A type error in one expression should not prevent the rest of the form from functioning. The diagnostic recording ensures that errors are observable by authors during testing.

3.11 Reserved Words

The following identifiers are reserved in FEL and MUST NOT be used as field keys, Data Source names, or extension function names:

and       or        not       in        true      false     null

Additionally, all built-in function names (§3.5) are reserved in the function namespace: a field key MAY be sum (it is referenced as $sum), but an extension function MUST NOT be named sum.

3.12 Extension Functions

Formspec allows domain-specific extensions to register additional functions with the FEL evaluator. Extension functions are the primary mechanism for extending FEL without modifying the core specification.

An extension function MUST:

1. Have a name that does not collide with any built-in function (§3.5) or reserved word (§3.11).
2. Be pure — given the same arguments, it MUST always return the same result. Extension functions MUST NOT have side effects.
3. Be total — it MUST return a value (possibly null) for every valid combination of argument types. It MUST NOT throw exceptions that propagate to the FEL evaluator; instead, it returns null and the processor records a diagnostic.
4. Declare its signature — parameter types and return type — so that the processor can perform static type checking during the Rebuild phase.

An extension function SHOULD be registered with the processor before the Definition is loaded. If a Definition references an extension function that is not registered, the processor MUST signal a definition error (§3.10.1).

Example. A healthcare extension function:

A Definition in a healthcare context might use:

bmi($weightKg, $heightCm)

The host application registers bmi as an extension function with signature bmi(number, number) → number and implementation weight / ((height / 100) ^ 2). The FEL evaluator treats it identically to a built-in function.

A Definition that uses extension functions SHOULD declare them in a top-level extensions array so that processors can detect missing extensions at load time rather than at evaluation time:

{
  "extensions": [
    {
      "namespace": "https://example.org/healthcare",
      "functions": [
        {
          "name": "bmi",
          "params": [
            { "name": "weightKg", "type": "number" },
            { "name": "heightCm", "type": "number" }
          ],
          "returns": "number",
          "description": "Body Mass Index: weight / (height_m)^2"
        }
      ]
    }
  ]
}

4. Definition Schema

4.0 Bottom Line Up Front

• This section defines the canonical Definition document shape for form structure and behavior declarations.
• A valid definition requires $formspec, url, version, status, title, and items.
• Definition identity is the immutable tuple (url, version); processors must not silently substitute versions.
• This BLUF is governed by schemas/definition.schema.json; generated references are the structural contract.

4.1 Top-Level Structure

A Formspec Definition is a JSON object. Conforming implementations MUST recognize the following top-level properties and MUST reject any Definition that omits a REQUIRED property.

{
  "$formspec": "1.0",
  "url": "https://example.gov/forms/annual-report",
  "version": "2025.1.0",
  "versionAlgorithm": "semver",
  "status": "active",
  "derivedFrom": "https://example.gov/forms/annual-report|2024.1.0",
  "title": "Annual Financial Report",
  "description": "...",
  "items": [],
  "binds": [],
  "shapes": [],
  "instances": {},
  "formPresentation": {
    "pageMode": "single",
    "labelPosition": "top",
    "density": "comfortable"
  },
  "extensions": {}
}

The canonical structural contract for Definition top-level properties is generated from schemas/definition.schema.json:

The generated table above defines required and optional properties. In this section, prose requirements describe semantics beyond structural constraints.

Implementations MUST preserve unrecognized top-level properties during round-tripping but MUST NOT assign semantics to them.

4.1.1 Form Presentation

The OPTIONAL formPresentation object on the Definition root provides form-wide presentation defaults. All properties within formPresentation are OPTIONAL and advisory. A conforming processor MAY ignore any or all of these properties.

Example:

{
  "formPresentation": {
    "pageMode": "wizard",
    "labelPosition": "top",
    "density": "compact",
    "showProgress": true,
    "allowSkip": false
  }
}

4.1.2 Page Mode Processing

A conforming processor MAY support any subset of page modes. When a processor does not support the declared pageMode, it MUST fall back to "single" and SHOULD emit an informative warning.

When a processor supports a given pageMode, it MUST satisfy the behavioral requirements below.

Wizard mode (pageMode: "wizard"):

1. The processor MUST render exactly one Page at a time.
2. The processor MUST provide Next/Previous navigation controls.
3. The processor MUST validate the current page before allowing forward navigation, unless allowSkip is true.
4. When showProgress is true, the processor MUST display a progress indicator showing the current step and total steps.

Tabs mode (pageMode: "tabs"):

1. The processor MUST render a tab bar with one tab per Page child, positioned according to tabPosition.
2. The processor MUST show exactly one Page’s content at a time.
3. The processor MUST allow the user to switch tabs by clicking or activating tab labels.
4. The processor MUST select the tab at index defaultTab on initial render.
5. All Pages MUST remain mounted; tab switching changes visibility, not lifecycle.

Property applicability:

• showProgress and allowSkip are meaningful only when pageMode is "wizard". Processors MUST ignore these properties for other modes.
• defaultTab and tabPosition are meaningful only when pageMode is "tabs". Processors MUST ignore these properties for other modes.

Note on naming: The Tabs component (§5.X) uses the property name position for tab bar placement. At the formPresentation level, the equivalent property is tabPosition. The rename avoids ambiguity with other component-level position properties (e.g., Panel).

Note: The page navigation gate in wizard mode constrains when validation errors are surfaced to the user, not what constitutes a valid submission. A form’s validation semantics (§5) are independent of its presentation mode.

4.2 Item Schema

An Item represents a single node in the form’s structural tree. Every Item MUST declare a key and a type. The type determines which additional properties are applicable.

{
  "key": "budget_section",
  "type": "group",
  "label": "Budget Information",
  "description": "Enter budget details for each line item",
  "labels": {
    "short": "Budget",
    "pdf": "Section III: Budget Information"
  },
  "children": []
}

4.2.1 Common Item Properties

The following properties are recognized on all Item types:

4.2.2 Group Items

A Group Item is a structural container. It organizes child Items into logical sections and MAY represent repeatable (one-to-many) data collections.

{
  "key": "line_items",
  "type": "group",
  "label": "Line Items",
  "repeatable": true,
  "minRepeat": 1,
  "maxRepeat": 50,
  "children": []
}

Group-specific properties:

A non-repeatable Group (the default) is rendered as a single structural section. Its children appear exactly once in the Response data.

4.2.3 Field Items

A Field Item represents a single data-entry point. Each Field produces exactly one value in the Response data (or one value per repetition if the Field is inside a repeatable Group).

{
  "key": "amount",
  "type": "field",
  "dataType": "decimal",
  "label": "Award Amount",
  "description": "Total federal award amount",
  "precision": 2,
  "prefix": "$",
  "children": []
}

Field-specific properties:

Core Data Types:

Implementations MAY support additional data types via the extensions mechanism. Unrecognized data types MUST be treated as "string" for storage and SHOULD produce a warning.

4.2.4 Display Items

A Display Item is a read-only, non-data-producing element. It is used for instructions, headings, and informational text. Display Items do NOT appear in the Response data.

{
  "key": "instructions",
  "type": "display",
  "label": "Complete all fields below. Required fields are marked with an asterisk."
}

Display-specific constraints:

• Display Items MUST NOT have children. If children is present, it MUST be an empty array.
• Display Items MUST NOT have a dataType.
• Binds referencing a Display Item’s key MAY use only the relevant property. All other bind properties (required, calculate, constraint, readonly) are meaningless for Display Items and MUST be ignored.

4.2.5 Presentation Hints

The OPTIONAL presentation object MAY appear on any Item (Field, Group, or Display). All properties within presentation are OPTIONAL and advisory.

A conforming processor MUST accept a presentation object without error. A conforming processor MAY ignore any property within presentation. Unknown keys within presentation MUST be ignored (forward-compatibility).

Presentation hints MUST NOT affect data capture, validation, calculation, or submission semantics.

4.2.5.1 Widget Hint

The widgetHint property is a string suggesting the preferred UI control. When present, the value SHOULD be one of the values listed in the tables below for the Item’s type and dataType. Custom values MUST be prefixed with x-. A processor receiving an incompatible or unrecognized widgetHint MUST ignore it and use its default widget for that Item type and dataType.

Group Items:

Display Items:

Field Items (by dataType):

When widgetHint is absent, unrecognized, or incompatible with the Item’s type or dataType, the processor MUST use its default widget for that dataType as listed above.

4.2.5.2 Layout

The layout sub-object provides spatial arrangement hints.

On Group Items:

On Field and Display Items:

Layout properties do NOT cascade from parent Group to child Items. Each Item’s layout is independent.

4.2.5.3 Style Hints

The styleHints sub-object provides semantic visual tokens. These are NOT CSS — renderers map them to their own palette and sizing.

4.2.5.4 Accessibility

The accessibility sub-object provides metadata for assistive technologies.

The role and liveRegion properties are named after ARIA concepts but this specification does NOT require ARIA. Renderers on non-web platforms SHOULD map to equivalent accessibility APIs. Renderers on platforms without accessibility APIs SHOULD ignore these properties.

4.2.5.5 Precedence and Interaction

1. formPresentation provides form-wide defaults. Item-level presentation properties override them per-property (not per-object).
2. Existing Item properties are complementary. The properties prefix, suffix, hint, description, labels, and semanticType retain their defined semantics and are NOT superseded by presentation.
3. widgetHint takes precedence over semanticType for widget selection. When a Field has both semanticType (e.g., "ietf:email") and widgetHint (e.g., "textInput"), the renderer SHOULD use the widgetHint for widget selection. When only semanticType is present, renderers MAY use it to infer a widget.
4. disabledDisplay on a Bind controls non-relevant rendering. presentation properties on the same Item control relevant-state rendering. There is no conflict.
5. No cascade. presentation properties do NOT cascade from parent Group to child Items. Each Item’s presentation is independent.

4.2.5.6 Forward Compatibility

The presentation object permits additional properties at its top level (unknown keys MUST be ignored). The nested sub-objects (layout, styleHints, accessibility) do NOT permit additional properties, to catch typographical errors.

This design allows future companion specifications to define additional keys inside presentation without breaking existing validators.

Informative note — Presentation tiers:

The presentation object serves as a baseline (Tier 1) for richer presentation systems:

• The Formspec Theme Specification (Tier 2) defines sidecar theme documents that override inline hints with a 3-level selector cascade, design tokens, and responsive page layouts.
• The Formspec Component Specification (Tier 3) defines component documents for full presentation-tree control, including custom parameterized components and slot bindings.

Companion specifications treat inline presentation hints as author-specified defaults that may be overridden by higher tiers.

Example — a Field with full presentation hints:

{
  "key": "annual_revenue",
  "type": "field",
  "label": "Annual Revenue",
  "dataType": "money",
  "prefix": "$",
  "presentation": {
    "widgetHint": "moneyInput",
    "layout": {
      "colSpan": 6
    },
    "styleHints": {
      "emphasis": "primary",
      "size": "large"
    },
    "accessibility": {
      "description": "Enter total revenue for the fiscal year",
      "liveRegion": "polite"
    }
  }
}

4.3 Bind Schema

A Bind attaches behavioral expressions to one or more data nodes identified by a path expression. Binds are the primary mechanism for declaring dynamic behavior — calculated values, conditional relevance, input constraints, and requiredness — without embedding logic in the item tree.

{
  "path": "budget_section.line_items[*].amount",
  "required": "true",
  "readonly": "false",
  "relevant": "$budget_section.has_budget = true",
  "calculate": null,
  "constraint": "$ >= 0",
  "default": "0"
}

4.3.1 Bind Properties

4.3.2 Inheritance Rules

Bind properties interact across the item hierarchy as follows:

• relevant: Inherited via logical AND. If any ancestor of a node is non-relevant, the node is non-relevant regardless of its own relevant expression. Implementations MUST enforce this: a child cannot be relevant when its parent is not.

• readonly: Inherited via logical OR. If any ancestor of a node is read-only, the node is read-only regardless of its own readonly expression. Implementations MUST enforce this: a child cannot be editable when its parent is read-only.

• required: NOT inherited. A required parent does not make its children required, and a required child does not make its parent required. Each required declaration stands alone.

• calculate: NOT inherited. Calculations execute only on the specific node targeted by the Bind.

• constraint: NOT inherited. Constraints are evaluated only against the specific node targeted by the Bind.

4.3.3 Path Syntax

Bind paths use dot-separated segments to navigate the item tree. The following forms are defined:

The [*] wildcard MUST be used when a Bind applies uniformly to all repetitions of a repeatable group. Index-based addressing ([@index = N]) SHOULD be used only in exceptional circumstances (e.g., binding a calculation to the first repetition only). FEL expression indexes ($repeat[n], @index) are 1-based as defined in the FEL normative grammar (§6.1–6.2). Resolved instance paths in ValidationResult entries use 0-based JSON array indexes (e.g., line_items[2].amount).

A path MUST resolve to at least one Item key in the Definition. If a path does not resolve, implementations MUST report a Definition error.

FieldRef vs Resolved Instance Path. Bind path and Shape target properties use FieldRef syntax — definition-time addresses with [*] wildcards. ValidationResult path properties use resolved instance paths with concrete 0-based indexes (e.g., line_items[2].amount). This unambiguously identifies the specific data node that failed validation.

4.4 Instance Schema

An Instance is a named secondary data source available to expressions within the Definition. Instances provide cross-referencing capability — for example, validating against prior-year data or populating option lists from external registries.

Instances are declared as properties of the top-level instances object. The property name serves as the instance’s identifier.

{
  "instances": {
    "priorYear": {
      "source": "https://api.example.gov/responses/2024/{{entityId}}",
      "static": false,
      "schema": {
        "total_expenditures": "decimal",
        "entity_name": "string"
      }
    },
    "stateCodes": {
      "source": "https://api.example.gov/reference/states",
      "static": true,
      "data": [
        {"code": "AL", "name": "Alabama"},
        {"code": "AK", "name": "Alaska"}
      ]
    }
  }
}

4.4.1 Instance Properties

At least one of source or data MUST be present. An Instance with neither MUST be rejected as a Definition error.

4.4.2 Referencing Instances in Expressions

Instance data is accessed in FEL expressions via the @instance() function:

@instance('priorYear').total_expenditures
@instance('stateCodes')[code = 'CA'].name

The argument to @instance() MUST be a string literal matching an instance name declared in the instances object. References to undeclared instances MUST produce a Definition error.

When instance data is unavailable (e.g., a network fetch fails and no data fallback exists), @instance() MUST return null. Expressions SHOULD be authored defensively to handle null instance data.

4.5 Variables

Variables are named computed values with lexical scoping. They provide a mechanism for defining intermediate calculations that can be referenced across multiple Binds, Shapes, and other expressions without repetition. The design is borrowed from FHIR SDC’s variable extension.

Variables are declared in the top-level variables array.

{
  "variables": [
    {
      "name": "totalBudget",
      "expression": "sum($line_items[*].amount)",
      "scope": "budget_section"
    },
    {
      "name": "priorYearTotal",
      "expression": "@instance('priorYear').total_expenditures",
      "scope": "#"
    }
  ]
}

4.5.1 Variable Properties

4.5.2 Evaluation Semantics

Variables are continuously recalculated. Whenever any dependency of a variable’s expression changes, the variable’s value MUST be recomputed before any dependent expressions are evaluated. This is analogous to XForms calculate and FHIR SDC calculatedExpression.

Variables MUST NOT form circular dependencies. If a circular dependency is detected, implementations MUST report a Definition error and MUST NOT attempt evaluation.

The evaluation order of variables MUST respect the dependency graph: if variable A depends on variable B, then B MUST be evaluated before A. Within the same dependency tier, evaluation order is implementation-defined.

For one-time initialization semantics (compute once at Response creation, never recalculate), use initialValue on the Item rather than a variable.

4.6 Option Sets

Option Sets are named, reusable option lists declared at the top level of a Definition. They allow multiple choice or multiChoice fields to reference the same options without duplication.

Option Sets are declared in the top-level optionSets object. The property name serves as the set’s identifier.

{
  "optionSets": {
    "yes_no_na": {
      "options": [
        { "value": "yes", "label": "Yes" },
        { "value": "no", "label": "No" },
        { "value": "na", "label": "Not Applicable" }
      ]
    },
    "agency_list": {
      "source": "https://api.sam.gov/agencies",
      "valueField": "code",
      "labelField": "name"
    }
  }
}

4.6.1 OptionSet Properties

An OptionSet is defined by one of:

A choice or multiChoice field references a named option set via the optionSet property on the Field item (§4.2.3).

4.7 Screener Routing

A Screener is a routing mechanism that classifies respondents and directs them to the appropriate target Definition. Screeners are declared in the optional screener property of a Definition.

{
  "screener": {
    "items": [
      {
        "key": "award_amount",
        "type": "field",
        "dataType": "money",
        "label": "Total federal award amount"
      }
    ],
    "binds": [
      { "path": "award_amount", "required": "true" }
    ],
    "routes": [
      {
        "condition": "moneyAmount($award_amount) < 250000",
        "target": "https://grants.gov/forms/sf-425-short|1.0.0",
        "label": "SF-425 Short Form"
      },
      {
        "condition": "true",
        "target": "https://grants.gov/forms/sf-425|2.1.0",
        "label": "SF-425 Full Form"
      }
    ]
  }
}

4.7.1 Screener Properties

Routes are evaluated in declaration order. The first route whose condition evaluates to true wins. A route with "condition": "true" acts as a default/fallback.

Screener items are NOT part of the form’s instance data — they exist only for routing purposes. A Definition with a screener section MAY also contain regular items and binds; in this case the screener acts as a gating step before the main form.

5. Validation

5.1 Severity Levels

Formspec defines three severity levels for validation results, borrowed from SHACL with modified conformance semantics:

Conformance Rule (VC-01): A Response is valid if and only if zero validation results with severity "error" exist. Warning-level and info-level results do NOT affect validity. This differs from SHACL, where any validation result of any severity indicates non-conformance.

Implementations MUST clearly distinguish severity levels in the user interface. Error-level results SHOULD be presented with prominent visual treatment (e.g., red borders, error icons). Warning-level results SHOULD be visually distinct from errors (e.g., yellow/amber treatment).

5.2 Validation Shape Schema

A Shape is a named, composable validation rule set. Shapes provide validation logic that operates at a higher level than individual Bind constraints — cross-field checks, conditional rules, and composite validations. The design is borrowed from SHACL’s shape concept, adapted for JSON data.

{
  "shapes": [
    {
      "id": "budget_total_check",
      "target": "budget_section",
      "severity": "error",
      "message": "Line item amounts must sum to the total budget",
      "code": "BUDGET_SUM_MISMATCH",
      "constraint": "sum($line_items[*].amount) = $total_budget"
    }
  ]
}

5.2.1 Shape Properties

5.2.2 Composition Operators

Shapes MAY be composed from other Shapes using the following operators, borrowed from SHACL’s logical constraint components:

Each element in a composition operator (and the single string value of not) may be either:

• A shape id string referencing another defined shape in the definition’s shapes array — the referenced shape is evaluated and its pass/fail result is used; or
• An inline FEL boolean expression string — the expression is evaluated directly and its boolean result is used.

A shape id is resolved by looking it up in the definition’s shapes array; if not found, the element is treated as an inline FEL expression.

When a composition operator is present, the constraint property is OPTIONAL. If both constraint and a composition operator are present, they are combined with implicit AND: the Shape passes only if the constraint evaluates to true AND the composition operator’s condition is met.

Example — disjunctive composition using shape id references:

{
  "id": "contact_info_complete",
  "target": "#",
  "severity": "error",
  "message": "Provide either email or phone number",
  "or": ["has_email", "has_phone"]
}

Example — disjunctive composition using inline FEL expressions:

{
  "id": "contact_info_complete",
  "target": "#",
  "severity": "error",
  "message": "Provide either email or phone number",
  "or": ["present($email)", "present($phone)"]
}

Inline FEL is simpler and more ergonomic when the condition does not need to be reused across multiple shapes. Shape id references remain useful for sharing named constraints and for nested composition.

Composition MAY be nested: a referenced Shape MAY itself use composition operators. Implementations MUST detect circular references among Shapes and report a Definition error.

5.3 Validation Result Schema

Each failed constraint — whether from a Bind constraint, a Bind required check, a type check, or a Shape — produces a structured ValidationResult. The schema is borrowed from SHACL’s Validation Result vocabulary.

{
  "path": "budget_section.total_budget",
  "severity": "error",
  "message": "Line item amounts must sum to the total budget",
  "code": "BUDGET_SUM_MISMATCH",
  "shapeId": "budget_total_check",
  "value": 50000,
  "context": {
    "expectedTotal": 75000,
    "actualTotal": 50000
  }
}

5.3.1 ValidationResult Properties

Implementations MUST produce ValidationResults for all of the following condition types:

1. Type mismatch — the value does not conform to the Field’s dataType.
2. Required violation — a required node has an empty value.
3. Bind constraint failure — a Bind’s constraint evaluates to false.
4. Shape constraint failure — a Shape’s constraint or composition evaluates to invalid.
5. Repeat cardinality violation — a repeatable Group has fewer than minRepeat or more than maxRepeat repetitions.

5.4 Validation Report Schema

A ValidationReport aggregates all ValidationResults for a given Response at a point in time.

{
  "valid": true,
  "results": [],
  "counts": {
    "error": 0,
    "warning": 2,
    "info": 1
  },
  "timestamp": "2025-01-15T10:30:00Z"
}

5.4.1 ValidationReport Properties

The canonical structural contract for ValidationReport properties is generated from schemas/validationReport.schema.json:

Implementations MUST ensure that valid is consistent with counts.error: valid MUST be true when counts.error is 0 and false otherwise.

5.5 Validation Modes

Formspec defines three validation modes controlling when the validation pipeline executes. Validation mode is a runtime concern, not part of the Definition. Implementations MUST support all three modes and MUST support switching between modes at runtime without data loss.

Critical Rule (VE-05): Saving data MUST never be blocked by validation. Regardless of the active validation mode, an implementation MUST allow the user (or calling system) to persist the current state of the Response data. Validation results are advisory until the point of submission. Only the submission action requires valid = true (i.e., zero error-level results).

Implementations MAY offer a "continuous-soft" variant where validation runs continuously but results are displayed only after the user has interacted with (blurred) the relevant field. This is a presentation-layer concern and does not constitute a distinct validation mode.

Per-Shape Timing Interaction: Individual Shapes MAY declare a timing property (§5.2.1) that controls when they fire ("continuous", "submit", "demand"). The global validation mode acts as an override:

• When the global mode is "disabled", no shapes fire regardless of timing.
• When the global mode is "deferred", all shapes (including "continuous") are deferred.
• When the global mode is "continuous" (default), shapes fire per their individual timing.

5.6 Non-Relevant Field Handling

When a node’s relevant Bind expression evaluates to false (or when any ancestor is non-relevant per the inheritance rules in §4.3.2), the following rules apply:

1. Validation suppression. Validation rules targeting the non-relevant node MUST NOT execute. The node MUST NOT produce any ValidationResults. This includes Bind constraints, Shape constraints, required checks, and type checks.

2. Submission behavior. The node’s treatment in the submitted Response is governed by the nonRelevantBehavior property (Definition-level default, overridable per-Bind). The three modes are:

   • "remove" (DEFAULT) — non-relevant nodes and descendants are excluded from the submitted Response.
   • "empty" — non-relevant nodes are retained but values set to null.
   • "keep" — non-relevant nodes are retained with current values.

3. Required suppression. A non-relevant node is never required, regardless of its required Bind. Implementations MUST NOT produce a required- violation ValidationResult for a non-relevant node.

4. Calculation continuation. A non-relevant node’s calculate Bind MUST continue to evaluate. The computed value exists in the in-memory data model and MAY be referenced by other expressions. For user-input fields that become non-relevant, the excludedValue Bind property (§4.3.1) controls what downstream expressions see: "preserve" (default, last value) or "null" (expressions see null). Submission behavior is governed separately by nonRelevantBehavior (rule 2).

5. Re-relevance. When a previously non-relevant node becomes relevant again, its value is restored. If a default is declared on the node’s Bind, the default value MUST be applied. If no default is declared, the node retains whatever value it had before becoming non-relevant.

5.7 External Validation Results

External systems — server-side APIs, third-party validators, business rule engines — MAY inject validation results into the Formspec validation pipeline. This enables validation logic that cannot be expressed in FEL (e.g., database lookups, cross-system consistency checks).

{
  "path": "entity.ein",
  "severity": "error",
  "message": "EIN not found in IRS database",
  "code": "EIN_NOT_FOUND",
  "source": "external",
  "sourceId": "irs-ein-lookup"
}

5.7.1 External Result Requirements

External validation results conform to the ValidationResult schema (§5.3) with the following additional properties and constraints:

5.7.2 Merging Rules

• External results MUST be merged into the ValidationReport alongside Definition-derived results.
• External results with severity "error" MUST be included in the valid determination. An external error blocks submission, just as a Definition-derived error does.
• External results MUST be included in the counts aggregation.
• Implementations MUST support injecting external results at any time during the form session — not only at submission.
• When the same path + code combination is injected multiple times, the most recent result SHOULD replace the prior one (idempotent injection).
• Implementations SHOULD provide a mechanism to clear external results (e.g., when the external system confirms the issue has been resolved).

6. Versioning & Evolution

6.1 Identity Model

A Definition is identified by its canonical url. The url represents the logical form — it is stable across versions. All versions of the same logical form share the same url and differ only in their version property.

The fully qualified reference to a specific Definition version uses the pipe syntax:

url|version

For example:

https://example.gov/forms/annual-report|2025.1.0

When a reference omits the |version suffix, it refers to the logical form without specifying a version. The resolution semantics of unversioned references are context-dependent:

• In a Response’s definition property, the version MUST be specified. Unversioned references are invalid in this context (§6.4).
• In derivedFrom, a plain URI string indicates derivation from the logical form in general. An object form { "url": "...", "version": "..." } pins derivation to a specific version.
• In $ref composition, an unversioned reference SHOULD resolve to the latest "active" version at assembly time.

6.2 Version Algorithms

The versionAlgorithm property governs interpretation and ordering of version strings. Conforming implementations MUST support all four algorithms:

When versionAlgorithm is absent, implementations MUST default to "semver". A version string that does not conform to its declared algorithm MUST be treated as a Definition error.

6.2.1 Version Semantics for Form Definitions

When versionAlgorithm is "semver", the following guidance applies to form definition changes. This guidance is RECOMMENDED, not REQUIRED.

6.3 Status Lifecycle

Every Definition MUST declare a status. The permitted values and their lifecycle transitions are:

  draft ────▶ active ────▶ retired
    ▲                        │
    └──────────────────────┘
    (new version, not same Definition)

• "draft" — The Definition is under development. It SHOULD NOT be used for production data collection. Implementations MAY restrict access to draft Definitions to authoring tools and preview environments.

• "active" — The Definition is in production. New Responses SHOULD reference active Definitions. Multiple versions of the same logical form MAY be active simultaneously (e.g., during a transition period).

• "retired" — The Definition is no longer in use for new data collection. Existing Responses that reference a retired Definition remain valid and MUST still be processable. New Responses SHOULD NOT reference retired Definitions. Implementations MAY enforce this as a hard constraint.

Transition constraints:

• A Definition MUST NOT transition backward: active → draft and retired → active are forbidden for the same Definition version.
• To revise a retired form, authors MUST create a new version with status "draft" and progress it through the lifecycle independently.
• The transition draft → active SHOULD be gated by a validation step confirming that the Definition is internally consistent (all paths resolve, no circular dependencies, all referenced Shapes exist, etc.).

6.4 Response Pinning

A Response MUST reference a specific Definition version using definitionUrl and definitionVersion properties:

{
  "definitionUrl": "https://example.gov/forms/annual-report",
  "definitionVersion": "2025.1.0",
  "status": "in-progress",
  "authored": "2025-01-15T14:30:00Z",
  "data": {}
}

Pinning Rule (VP-01): A Response is always validated against the Definition version it references, even if a newer version of the same logical form exists. This guarantees that existing Responses are never retroactively invalidated by Definition changes.

Implication: If a Definition author discovers a flaw in version 2025.1.0 after Responses have been collected, they MUST publish a new version (e.g., 2025.1.1) and migrate Responses explicitly. They MUST NOT alter version 2025.1.0 in place.

Immutability Rule (VP-02): Once a Definition version reaches "active" status, its content MUST NOT be modified. Any change — however minor — requires a new version. This ensures that the url|version pair is a stable, immutable reference.

6.5 Variant Derivation

A Definition MAY declare derivedFrom to indicate it is a variant of another Definition. Common derivation scenarios include:

• Year-over-year updates — annual-report version 2025.1.0 derived from { "url": "https://example.gov/forms/annual-report", "version": "2024.1.0" }.
• Long form / short form — annual-report-short derived from the annual-report definition (unversioned URI string).
• Domain-specific specialization — annual-report-healthcare derived from a specific version via the object form.

Semantics: derivedFrom is informational only. It does NOT imply behavioral inheritance, structural inclusion, or any runtime linkage between the parent and derived Definitions. The derived Definition is a fully independent artifact.

derivedFrom enables the following tooling capabilities:

1. Change analysis — Tooling MAY compare the derived Definition to its parent to highlight structural and behavioral differences.
2. Pre-population — Implementations MAY use derivedFrom to identify Responses to the parent Definition that can serve as pre-population sources for the derived Definition, mapping data by matching key values.
3. Lineage tracking — Audit systems MAY use derivedFrom to construct the full derivation history of a Definition.

6.6 Modular Composition

Definitions MAY include items from other Definitions via the $ref property on a Group Item. This enables reuse of common item sets (e.g., demographics, address blocks, signature sections) across multiple Definitions.

{
  "key": "demographics",
  "type": "group",
  "label": "Demographics",
  "$ref": "https://example.gov/forms/common/demographics|1.0.0",
  "keyPrefix": "demo_"
}

6.6.1 Composition Properties

6.6.2 Assembly

Assembly is the process of resolving all $ref inclusions to produce a self-contained Definition with no external references. Assembly SHOULD be performed at publish time (when a Definition transitions from "draft" to "active"). The output of assembly is a fully expanded Definition that can be processed without access to the referenced Definitions.

Assembly rules:

1. All root-level Items from the referenced Definition MUST be inserted as children of the Group that declares the $ref.
2. If keyPrefix is specified, every key in the imported items (including deeply nested children) MUST be prefixed. Bind paths, Shape targets, and variable scopes referencing those keys MUST be updated accordingly.
3. Binds, Shapes, and Variables from the referenced Definition MUST be imported into the host Definition. Their paths and scopes MUST be rewritten to reflect the new position in the host item tree and any keyPrefix transformation.
4. If a key collision exists after prefix application, the assembler MUST report an error and abort.
5. $ref resolution MUST be recursive: if the referenced Definition itself contains $ref inclusions, those MUST be resolved as well.
6. Circular $ref chains MUST be detected and reported as a Definition error.

The assembled Definition SHOULD carry an assembledFrom metadata array listing all referenced Definitions:

{
  "assembledFrom": [
    {
      "url": "https://example.gov/forms/common/demographics",
      "version": "1.0.0",
      "keyPrefix": "demo_"
    }
  ]
}

This metadata is informational and MUST NOT affect runtime behavior.

6.7 Version Migrations

Definitions MAY declare a migrations section describing how to transform Responses from prior versions into the current version’s structure. This addresses the operational gap when a major version introduces breaking changes.

{
  "migrations": {
    "from": {
      "2.1.0": {
        "description": "Restructured budget section; split other_costs into subcategories",
        "fieldMap": [
          {
            "source": "expenditures.other_costs",
            "target": "expenditures.miscellaneous.total",
            "transform": "preserve"
          },
          {
            "source": "indirect_rate",
            "target": null,
            "transform": "drop"
          }
        ],
        "defaults": {
          "expenditures.miscellaneous.description": "",
          "reporting.frequency": "quarterly"
        }
      }
    }
  }
}