F
Forma
Specification Working Group
Overview / Conformance
Interoperability rules

Conformance

This section defines what a producer must emit, what a consumer must accept, and what validators must check in order to claim Forma v1 compatibility.

Producer conformance

  • Must emit valid Forma JSON per schema
  • Must include required document fields
  • Must preserve child order
  • Must use enums and required types correctly
  • Must emit issues for unsupported or ambiguous cases when relevant

Consumer conformance

  • Must accept any valid Forma v1 document for the minor line(s) it implements (e.g. 1.0.x)
  • Must ignore unknown extension fields safely
  • Must not fail on absent optional fields
  • Should use issues, confidence, and flags in downstream behavior

Validator conformance

  • Must validate against JSON Schema
  • Must report schema violations clearly
  • Should report semantic warnings beyond schema when possible

Compatibility claims

An implementation may claim Forma v1 Producer, Forma v1 Consumer, or Forma v1 Validator conformance only if it satisfies the relevant requirements in this section.

Interoperability minimum

Third-party interoperability requires schema validity, stable core fields, safe extension handling, and preservation of node ordering and ids within document scope.

Graph invariants (normative)

Forma documents represent a directed tree (or forest) of nodes using parentId and ordered children. The following invariants are required for interoperability.

  • Node id values MUST be unique within a document.
  • If a node has parentId set to P, then the node id MUST appear exactly once in P.children.
  • If a node id appears in P.children, that child node MUST have parentId equal to P.id.
  • A node MUST NOT appear in more than one parent’s children array.
  • The parent/child graph MUST be acyclic.
  • Consumers MUST interpret child order from children. Consumers MUST NOT rely on the order of the top-level nodes array.

Roots and screens

  • Nodes with absent or null parentId are roots.
  • Producers SHOULD emit one or more screen root nodes as entry points.

Validator requirements (beyond JSON Schema)

JSON Schema validation alone cannot enforce cross-node references. A Forma v1 Validator SHOULD implement the checks above and SHOULD report violations as clear errors.

  • When tokens is present, validators SHOULD verify that all token references {token.key} point to declared keys.

Machine-readable normative bundle

For AI agent interoperability and automated tooling, this repo ships a machine-readable bundle of the most important normative requirements, registries, and algorithms.

  • spec/normative.json: structured requirements, registries, and step-by-step algorithms (core + AI-native deterministic)

AI-native deterministic profile (optional)

Implementations may additionally claim Forma v1 AI-native Deterministic conformance if they implement the execution semantics described in the AI-native extension.

  • Consumers MUST execute eventHandlers deterministically (stable handler selection, ordering, and action sequencing).
  • Consumers MUST support on: "event" handlers and trigger them from emit actions.
  • Consumers MUST implement state initialization from extensions.ai_native.state.*.initial when present.
  • Consumers SHOULD implement structured state bindings in dataBindings and apply binding updates before executing change handlers.
  • For deterministic verification, consumers SHOULD support capability fixtures and prefer invoke.payload.fixtureId over live tool calls.

AI-native interoperability fixtures

This repo includes a minimal reference executor and a small set of deterministic trace fixtures to support agent interoperability.

  • Reference executor: tools/execute_ai_native.py
  • Trace fixtures: conformance/ai_native/traces/
  • Trace schema: www/schema/forma.ai_native_trace.schema.json

Example usage: python3 tools/execute_ai_native.py --doc www/examples/ai_native_interactions.json --on click --scope cmp_submit

Non-normative: this repo includes a reference validator script at tools/validate_forma.py that performs JSON Schema validation (when available), enforces these graph invariants, and validates token references when a token dictionary is present.