Schema reference

This section defines the required objects, fields, types, and enums for production Forma documents. The JSON Schema file is the machine-checkable companion to this page.

Primary objects

FormaDocument
SourceRef
FormaNode
Layout
Style
Issue

Required enums

Node types: screen, component, container, text, image, icon
Roles: button, input, card, modal, nav, list, container, text, image
Layout types: flex, stack, absolute
Severity: info, warning, error

Token references

Token references are strings of the form {token.key.path}. The value inside the braces MUST match a key in the document-level tokens dictionary when that dictionary is present.

Token keys are dot-delimited identifiers such as space.2 or color.brand.primary.

Token dictionary

tokens is an optional flat dictionary mapping token keys to token definitions. Token definitions are typed and may include units.

Token scope in v1 is document-global. Overrides are not standardized in the core schema. Forma v1 defines an optional extensions.token_overrides container for mode-based overrides.

Example: tokensJSON

{
  "space.2": {"type": "dimension", "value": 8, "unit": "px"},
  "radius.md": {"type": "radius", "value": 8, "unit": "px"},
  "color.brand.primary": {"type": "color", "value": "#2F6BFF"}
}

Token definition shapes (normative)

Token definitions are typed objects. Producers SHOULD emit literal values inside token definitions (not token references).

Example: typography tokenJSON

{
  "typography.label.md": {
    "type": "typography",
    "value": {
      "fontFamily": "Inter",
      "fontSize": 14,
      "fontWeight": 600,
      "lineHeight": 20,
      "letterSpacing": 0
    }
  }
}

Border and shadow tokens

Example: shadow + border tokensJSON

{
  "shadow.sm": {
    "type": "shadow",
    "value": {"x": 0, "y": 2, "blur": 8, "spread": 0, "color": "rgba(0,0,0,0.12)"}
  },
  "border.default": {
    "type": "border",
    "value": {"width": 1, "style": "solid", "color": "#E5E7EB"}
  }
}

radius tokens are dimension-like and include a unit.

Object	Field	Type	Required	Notes
FormaDocument	version	string	Yes	Semantic version, v1 requires 1.x.y
FormaDocument	source	SourceRef	Yes	Originating tool and file reference
FormaDocument	nodes	FormaNode[]	Yes	Flat node list with parent-child links
FormaDocument	tokens	object	No	Optional token dictionary
FormaDocument	metadata	object	No	Optional producer metadata
FormaDocument	extensions	object	No	Optional extension container; consumers MUST ignore unknown entries safely. The spec defines extensions.ai_native as an optional AI-Native layer in v1.1.
FormaDocument	issues	Issue[]	No	Document-level issues
SourceRef	tool	string	Yes	Example: figma, sketch
SourceRef	fileId	string	No	Stable source file reference if available
FormaNode	id	string	Yes	Stable within document scope
FormaNode	type	enum	Yes	One of the required node types
FormaNode	name	string	Yes	Human-readable source or normalized name
FormaNode	role	string	No	Semantic role when known or inferred (open vocabulary; recommended registry in spec)
FormaNode	parentId	string\|null	No	Null or absent for roots
FormaNode	children	string[]	No	Ordered child node ids
FormaNode	layout	Layout	No	Required for structural nodes unless not applicable
FormaNode	style	Style	No	Token-first style object
FormaNode	text	string	No	Allowed on text nodes
FormaNode	textRuns	RichTextRun[]	No	Optional rich text spans for text nodes (start/end ranges into text)
FormaNode	asset	AssetRef	No	Recommended for image and icon nodes
FormaNode	alt	string	No	Optional accessibility alt text for images/icons
FormaNode	source	SourceRef	No	Per-node provenance
FormaNode	confidence	number	No	0.0–1.0 inclusive
FormaNode	flags	string[]	No	Ambiguity, fallback, unsupported data markers
Issue	severity	enum	Yes	info, warning, error
Issue	code	string	Yes	Machine-readable issue code
Issue	message	string	Yes	Human-readable explanation

Canonical node exampleJSON

{
  "id": "cmp_button_primary",
  "type": "component",
  "name": "Button/Primary",
  "role": "button",
  "parentId": null,
  "children": ["txt_button_primary_label"],
  "layout": {
    "type": "flex",
    "direction": "row",
    "align": "center",
    "justify": "center",
    "gap": "{space.2}",
    "padding": {"x": "{space.4}", "y": "{space.2}"}
  },
  "style": {
    "background": "{color.brand.primary}",
    "text": "{typography.label.md}",
    "radius": "{radius.md}"
  },
  "confidence": 0.97,
  "flags": []
}

Machine validation

Use the shipped schema for validation in producers, CI, and third-party consumers.

Open JSON Schema

Absolute layout positioning

For layout.type of absolute, producers MUST provide a positioning basis. Forma v1 supports two optional mechanisms:

layout.frame: explicit x, y, width, height
layout.insets: top/right/bottom/left offsets

Values may be numbers, token references, or literals. Coordinates are interpreted in the parent’s coordinate space with origin at the parent’s top-left.

Component instances, variants, and slots

Component nodes MAY include a component object to describe whether the node is a reusable definition or an instance, how it relates to a definition, and which variant/slots are active.

Example: component metadataJSON

{
  "id": "cmp_button_instance",
  "type": "component",
  "name": "Button/Primary",
  "component": {
    "kind": "instance",
    "definitionId": "cmp_button_primary",
    "variant": {"size": "md", "tone": "primary"},
    "slots": {"icon": ["ic_arrow"], "label": ["txt_label"]}
  }
}

AI-native behavior (optional)

Forma v1.1 defines an optional AI-native extension under extensions.ai_native to standardize interaction semantics for deterministic execution.

eventHandlers: event routing (click/submit/change/event)
actions: executable steps (navigate, submit, setState, emit, invoke)
state: state store registry with deterministic initial values
dataBindings: binds component properties to state using JSON Pointer
capabilities/events: registries with JSON Schema contracts and optional fixtures

See the Extensions page for the deterministic execution rules.

Example: deterministic invoke fixtureJSON

{
  "extensions": {
    "ai_native": {
      "contractDialect": "jsonschema-2020-12",
      "capabilities": {
        "auth.validateCredentials": {
          "input": {"type": "object", "properties": {"email": {"type": "string"}}},
          "output": {"type": "object", "properties": {"ok": {"type": "boolean"}}},
          "fixtures": [{"id": "ok", "args": {"email": "a@b.com"}, "result": {"ok": true}}]
        }
      },
      "actions": {
        "act_validate": {
          "type": "invoke",
          "target": "auth.validateCredentials",
          "payload": {"fixtureId": "ok", "bindResultTo": {"store": "session", "pointer": "/auth"}}
        }
      }
    }
  }
}

Style border and shadow

style.border and style.shadow MAY be either a token reference (preferred) or a structured object.

Example: structured border + shadowJSON

{
  "style": {
    "border": {"width": 1, "style": "solid", "color": "{color.border.default}"},
    "shadow": {"x": 0, "y": 2, "blur": 8, "color": "rgba(0,0,0,0.12)"}
  }
}

Token override modes (optional)

Forma v1 defines an optional extension for mode-based token overrides under extensions.token_overrides. Consumers that do not implement it MUST ignore it safely.

For interoperability, override modes SHOULD only override values for token keys already declared in the document-level tokens dictionary.

Example: extensions.token_overridesJSON

{
  "extensions": {
    "token_overrides": {
      "version": "1.1.0",
      "defaultMode": "light",
      "modes": {
        "light": {"tokens": {"color.bg": {"type": "color", "value": "#FFFFFF"}}},
        "dark": {"tokens": {"color.bg": {"type": "color", "value": "#0B1220"}}}
      }
    }
  }
}