# Number formats

> The catalogue of number formats an item can use in Layerz, with their Excel equivalent and a rendered sample, plus custom formats per model.

This is the same catalogue the MCP server gives agents (`format-spec://reference`), with samples rendered by the product's own formatter.

An item's `format` is a NAME resolved against this catalog (pre-installed +
the model's custom `model.formats`). An unknown name is rejected at write time
(`UNKNOWN_FORMAT`). Examples below are rendered by the app's actual display
engine as `positive / negative / zero`; web rendering follows the model's
`number_locale` (`en` shown here), Excel export uses the `excel_format`
string verbatim.

## Pre-installed number formats

Sample values: amounts `1234.56`, percents `0.125`, multiples `2.5`.

| Name | excel_format | Rendered (pos / neg / zero) |
| --- | --- | --- |
| `default` | `#,##0;(#,##0);-` | `1,235` / `(1,235)` / `-` |
| `decimal_2` | `#,##0.00` | `1,234.56` / `-1,234.56` / `0.00` |
| `decimal_neg` | `#,##0;(#,##0);-` | `1,235` / `(1,235)` / `-` |
| `integer` | `#,##0` | `1,235` / `-1,235` / `0` |
| `multiple` | `0.00"x";(0.00"x");-` | `2.50x` / `(2.50x)` / `-` |
| `percent` | `0%` | `13%` / `-13%` / `0%` |
| `percent_neg` | `0%;(0%);-` | `13%` / `(13%)` / `-` |
| `percent_2` | `0.00%` | `12.50%` / `-12.50%` / `0.00%` |

Note the zero convention: `default` is
accounting-style: thousands separator, parenthesized negatives, **dash for
zero**: while `integer`/`decimal_2` render zero as a plain `0` / `0.00`
and negatives with a minus sign. For money lines the accounting family
(`default`/`decimal_neg`/`currency`) is usually what finance users expect.

## Pre-installed date formats

Sample date: 31 March 2026. Values are Excel date serials; `0` renders as `-`.

| Name | excel_format | Rendered |
| --- | --- | --- |
| `date_dmy` | `dd/mm/yyyy` | `31/03/2026` |
| `date_dmmmyy` | `dd-mmm-yy` | `31-Mar-26` |
| `date_mmmyy` | `mmm-yy` | `Mar-26` |
| `date_dmmm` | `dd-mmm` | `31-Mar` |

The magic name `date` (no catalog entry) renders a locale-default short date
(`03/31/2026` in `en`).

## Currency formats (resolved live)

`currency` and `currency_2` (2 decimals) are reserved names resolved at
render/export time from the model's FINANCE.md `currency` code: never
persisted, so changing the model currency re-formats every `currency` item.
Prefix currencies (USD, GBP, JPY, CNY) put the symbol before the amount;
everything else is a suffix with a non-breaking space.

| FINANCE.md currency | excel_format (`currency`) | Rendered (pos / neg / zero) |
| --- | --- | --- |
| `USD` | `"$"#,##0;("$"#,##0);-` | `$1,235` / `($1,235)` / `-` |
| `EUR` | `#,##0" €";(#,##0" €");-` | `1,235 €` / `(1,235 €)` / `-` |

## Custom formats

Add your own via the `meta` op of `layerz_patch` (`formats` field, same
batch as the items using them): `{ "formats": { "eur_k": { "name": "eur_k",
"excel_format": "#,##0,\" k€\";(#,##0,\" k€\");-" } } }`: a trailing comma
after the digit core divides by 1,000 (Excel thousands-scaling). To extend the
`default` convention, start from its string `#,##0;(#,##0);-`
(sections are `positive;negative;zero`). Custom entries appear in
`layerz_get_model` under `model.formats`.

## Colours, conditions, locale tags (Excel / Google Sheets grammar)

Bracket tokens work exactly as in Excel: never rendered as text:

- **Colours**: `[Red]`, `[Green]`, `[Blue]`, `[Black]`, `[White]`,
  `[Cyan]`, `[Magenta]`, `[Yellow]` (or `[Color 1]`–`[Color 8]`) colour
  the section that renders the value: `[Green]#,##0;[Red](#,##0);-` shows
  `1,235` / `(1,235)` / `-` with positives green and negatives red.
  The web maps them to Layerz's semantic tones (readable on light and dark
  fills); Excel paints its own colours from the same string.
- **Conditions**: `[>=1000]`, `[<0]`, `[=0]`, `[<>0]`… on the first two
  sections pick the section by value (the third is the fallback). In a
  conditional layout the value renders SIGNED, as in Excel:
  `[>=1000]#,##0,"K";#,##0` shows `1K` / `-1,235` / `0`.
- **Locale / currency tags**: `[$€-407]` renders its symbol (`€`), the
  locale id is dropped; `[$-409]` renders nothing.
- **`General`**: the plain number (up to 10 decimals, no grouping).

A malformed pattern (unbalanced quote or bracket, unknown token such as
`[Rde]`, more than 4 sections or 2 conditions) is rejected by the `meta` op.
