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.
{
"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, 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. |
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 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. The blueprint of a template is returned by GET /templates/:id.