# Model format

> The JSON shape of a Layerz model, its manifest, schema and inputs, the fields of an item, and the invariants every stored model satisfies.

A model is stored, versioned and exchanged as one JSON document in three parts. It is the shape returned by `GET /models/:id/snapshot` and by a version, and the shape accepted by `PUT /models/:id/snapshot`.

```json
{
  "manifest": {
    "metadata": { "company_name": "Acme SaaS plan", "currency": "EUR" },
    "finance_md": { "raw": "---\nfinance_md: \"0.1\"\n...", "source": "user" },
    "context": {
      "timelines": { "monthly": { "start": "2027-01-01", "end": "2029-12-31" } },
      "branches": [],
      "actuals_through": "2027-03"
    }
  },
  "schema": { "name": "Acme SaaS plan", "items": [], "listes": {} },
  "inputs": []
}
```

| Part       | Holds                                                                                                                                                                                                                |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `manifest` | Identity and context: name, subtitle, currency, the [FINANCE.md](/docs/reference/finance-md), and in `context` the timelines, the branches, the actuals cutover, the glyph, custom number formats and view settings. |
| `schema`   | Structure: `items`, a flat ordered array of every item, and `listes`, the list definitions.                                                                                                                          |
| `inputs`   | Values: typed series of assumptions, list elements, per-element series and imported values, each row tagged with its branch.                                                                                         |

## Items

`schema.items` is the single source of truth for the structure. The hierarchy is expressed by `parent_uid` and the order by `sort_index`, not by nesting. Common fields:

| Field                             | Meaning                                                                         |
| --------------------------------- | ------------------------------------------------------------------------------- |
| `uid`                             | Stable id, unique in the model. Every reference uses it.                        |
| `display_name`                    | The name: label and formula identifier, unique regardless of case.              |
| `role`                            | One of the [roles](/docs/concepts/items-and-roles).                             |
| `parent_uid`, `sort_index`        | Position in the hierarchy.                                                      |
| `timeline_ref`                    | `constant`, `monthly`, `quarterly` or `yearly`.                                 |
| `formula`                         | Expression of a formula line, by names. Its inputs are derived, never declared. |
| `source_uid`                      | The line a callup mirrors.                                                      |
| `opening_balance`                 | Opening of a balance.                                                           |
| `liste_ref`                       | The list a line is bound to.                                                    |
| `aggregation`                     | `sum`, `stock`, `average` or `first`: how the line folds across grains.         |
| `format`, `item_style`, `comment` | Presentation and notes.                                                         |
| `check`                           | `{ tolerance? }` when the line is a control.                                    |

Widgets add their own fields: `series` and `chart_type` on a chart, `target_uid` and `target_period` on a KPI, `table_rows` and `table_axis` on a mini-table, `span` and `position` on the dashboard grid. The full list of writable fields is the [items endpoint](/docs/api/items) schema.

## Invariants

Every stored model satisfies these rules; a write that would break one is refused or repaired at write time, never at read time:

- **No orphan reference.** Every parent, source, target, series and formula input points to an item of the model.
- **Roles hold their own fields only.** A formula is a total or an expression, never both; a callup has no timeline of its own; a section holds no value.
- **Values run at their line's grain.** A typed series always matches the grain of its line.
- **Lists are model-wide.** List elements are never specific to a branch, and a list holds at most 500 elements.
- **One write at a time.** A write based on a stale state is refused (HTTP 409) and retried on the current one.

## Blueprints

A blueprint is a higher-level form of the same model, for writing: sections with their items nested, items referenced by name rather than by id. Agents build with blueprints and edit with patches; see [Blueprint and patch](/docs/mcp/blueprint-and-patch). The blueprint of a template is returned by `GET /templates/:id`.
