Production schema
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
| 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 | 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 | enum | No | Semantic role when known or inferred |
| 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 | 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.