---
title: The document
description: A Framewerk spec is one JSON document whose optional top-level fields hold screens, components, styles, flows and content.
status: shipped
url: https://getairframe.com/framewerk/core/document
---

> Part of the Framewerk docs. Index of every page: /framewerk/llms.txt

# The document

A **spec** is one plain JSON document that describes an application's screens — their layout, styling, interactive state and navigation — designed to be written by hand, generated by an agent, diffed in review, and rendered identically by any conforming renderer.

Everything below is the whole public format. There are no hidden node types and no private extensions.

## Examples

The smallest useful spec is one screen with one text node:

**The smallest spec**

```json
{
  "formatVersion": "1.0",
  "screens": [
    {
      "id": "home",
      "layout": { "_id": "root", "type": "text", "content": "Hello" }
    }
  ]
}
```

A document with every top-level section populated:

**A document with state and navigation**

```json
{
  "formatVersion": "1.0",
  "project": { "name": "Coffee Cart", "defaultDevice": "iphone15" },
  "screens": [
    {
      "id": "menu",
      "stateVars": { "oatMilk": { "type": "boolean", "default": "false" } },
      "layout": {
        "_id": "menu-root",
        "type": "column",
        "gap": 16,
        "padding": 24,
        "children": [
          { "_id": "title", "type": "text", "variant": "heading", "content": "Coffee Cart" },
          { "_id": "oat", "type": "button", "content": "Toggle oat milk", "action": "toggleState(oatMilk)" },
          { "_id": "badge", "type": "badge", "content": "Oat milk", "showWhen": "$oatMilk == true" },
          { "_id": "order-btn", "type": "button", "variant": "primary", "content": "Order", "action": "navigate(order)" }
        ]
      }
    },
    {
      "id": "order",
      "layout": {
        "_id": "order-root",
        "type": "column",
        "gap": 16,
        "padding": 24,
        "children": [
          { "_id": "order-title", "type": "text", "variant": "heading", "content": "Order" },
          { "_id": "order-back", "type": "button", "content": "Back", "action": "back()" }
        ]
      }
    }
  ],
  "flows": [{ "from": "menu", "to": "order", "trigger": "Order button" }]
}
```

## Anatomy

```jsonc
{
  "formatVersion": "1.0",           // the version of the format this document follows
  "drafts":       [ /* string[]     — the draft parts it uses, e.g. "requirements" */ ],
  "project":      { /* ProjectMeta — name, theme, default device/style */ },
  "screens":      [ /* ScreenDef[]   — the screens */ ],
  "components":   { /* Record<string, ComponentDef> — reusable subtrees */ },
  "styles":       [ /* StyleDef[]    — token sets and rules */ ],
  "brands":       [ /* BrandDef[]    — brand identity that styles derive from */ ],
  "flows":        [ /* FlowDef[]     — screen-to-screen edges */ ],
  "flowPackages": [ /* FlowPackageDef[] — grouped multi-step journeys */ ],
  "content":      { /* ContentRegistry — localized labels and fixture data */ },
  "pages":        [ /* PageDef[]     — grouping for large projects */ ],
  "aliases":      { /* Record<string, string> — renamed-ID redirects */ }
}
```

Every field is optional.

| Field | Type | Notes |
| --- | --- | --- |
| `formatVersion` | string | The format version, as `major.minor`. See below. |
| `drafts` | string[] | The draft parts the document uses. See below. |
| `project` | `ProjectMeta` | Display name, theme, default device/style. |
| `screens` | `ScreenDef[]` | The screens; each has an `id` and a `layout` tree. |
| `components` | `Record<string, ComponentDef>` | Reusable subtrees, referenced by `component` nodes. |
| `styles` | `StyleDef[]` | Token sets and rules. |
| `brands` | `BrandDef[]` | Optional identity a style can be generated from. |
| `flows` | `FlowDef[]` | Documentation of navigation edges. |
| `flowPackages` | `FlowPackageDef[]` | Named multi-step journeys. |
| `content` | `ContentRegistry` | Localized labels (`$c()`) and fixtures (`$f()`). |
| `pages` | `PageDef[]` | Grouping for large projects. |
| `aliases` | `Record<string, string>` | `oldId → newId` redirects after a rename. |

### `formatVersion` and `drafts`

`formatVersion` says which version of the format the document was written against: `"1.0"` today. A reader accepts any minor version of a major version it knows, and refuses a major version it does not.

A document with no `formatVersion` is read as `"1.0"`. `validate()` reports that as a warning, never an error.

`drafts` names the draft parts the document uses. The one draft part of Framewerk 1 is [requirements](/framewerk/core/requirements.md), so a document that states a `formatVersion` and carries requirements also carries `"drafts": ["requirements"]`, and `validate()` reports an error when it does not.

A tool that writes documents can leave both to the package:

```ts
import { withFormatVersion } from "@framewerk/spec";

const document = withFormatVersion(spec); // states the version, names the draft parts in use
```

### `project`

| Field | Type | Notes |
| --- | --- | --- |
| `name` | string | Display name. |
| `version` | string | Your project's version — unrelated to the format version. |
| `theme` | `"wireframe" \| "blueprint" \| "high-fidelity"` | Rendering register. `wireframe` is the low-fidelity default. |
| `defaultDevice` | string | A device preset ID — see [Screens & devices](/framewerk/core/screens-and-devices.md). |
| `defaultStyle` | string | ID of the `StyleDef` applied when a screen names none. |

### `aliases`

A map of `oldId → newId`. When a screen or component is renamed, the old ID keeps resolving instead of breaking every `navigate()` that pointed at it. Resolution follows chains up to a bounded depth (`ALIAS_CHAIN_DEPTH`), so a cycle cannot hang a renderer.

## Stability

The document shape versions with `@framewerk/spec` under semver. Adding a top-level field or making an existing one optional is additive; removing one, or narrowing what it accepts, is breaking. The checked-in `api-report.md` in each package is the machine-checked record of the exported surface.