Browse the documentation

Reference

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.

{
  "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": []
}
PartHolds
manifestIdentity 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.
schemaStructure: items, a flat ordered array of every item, and listes, the list definitions.
inputsValues: 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:

FieldMeaning
uidStable id, unique in the model. Every reference uses it.
display_nameThe name: label and formula identifier, unique regardless of case.
roleOne of the roles.
parent_uid, sort_indexPosition in the hierarchy.
timeline_refconstant, monthly, quarterly or yearly.
formulaExpression of a formula line, by names. Its inputs are derived, never declared.
source_uidThe line a callup mirrors.
opening_balanceOpening of a balance.
liste_refThe list a line is bound to.
aggregationsum, stock, average or first: how the line folds across grains.
format, item_style, commentPresentation 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.