Cell Metadata

Cell metadata is the presentation and validation layer that travels alongside a cell's value: number and date formats, styles, conditional formatting, data validation, comments, hyperlinks, rich text, merges, and inline visualizations.

Most metadata is document state set through the UI, import/export flows, or product APIs. Grid source can also declare the portable subset that belongs with a binding: FORMAT, VALIDATE, and ## doc notes. Those declarations compile into the same presentation/input-policy layer and remain separate from the formula's computed value. See Declared Presentation.

This page documents the metadata vocabulary so authors and import/export code describe presentation the same way.

1. What A Cell Carries

A cell's value (a number, string, date, …) is computed by its formula. Its metadata is a separate record with these optional parts:

Field	Purpose
`unit`	A display unit label (prefix or suffix)
`numberFormat`	How a numeric value renders
`dateFormat`	How a date value renders
`booleanFormat`	How a boolean renders (text, yes/no, checkbox, …)
`style`	Font, color, alignment, borders
`conditionalFormats`	Style overrides driven by the value
`visualizations`	Inline data bars, color scales, sparklines, badges
`validation`	Allowed-input rules for editable cells
`merge`	Row/column span for merged cells
`hyperlink`	A link target with optional tooltip/display
`richText`	Mixed-style runs within one cell
`comment`	A note attached to the cell

Presentation metadata never changes the cell's computed value. Validation is an input policy: it can reject a write without changing the stored value, and a source-declared VALIDATE clause on a computed cell is a compile-time static assertion rather than runtime metadata.

2. Number Formats

numberFormat controls how a numeric value displays.

Field	Meaning
`style`	`"decimal"`, `"percent"`, `"currency"`, or `"scientific"`
`pattern`	Verbatim Excel format string (preserved on import for fidelity)
`sections`	Parsed Excel sections (`positive;negative;zero;text`)
`currencySymbol` / `currency`	Currency display
`minimumFractionDigits` / `maximumFractionDigits`	Decimal places
`useGrouping`	Thousands separators
`locale`	Locale for grouping/decimal symbols

Grid renders from the structured fields; the pattern is round-tripped so Excel export preserves custom format grammar Grid does not fully model yet.

For formatting inside a formula result (rather than as cell metadata), use TEXT(value, "$#,##0.00") or an interpolation format spec (`{A1:"0.0%"}`). See functions.md.

3. Date And Boolean Formats

dateFormat is a single pattern (an Excel-style date format such as yyyy-mm-dd).

booleanFormat.style chooses how a boolean renders:

Style	Renders as
`text`	`TRUE` / `FALSE`
`yesNo`	Yes / No
`passFail`	Pass / Fail
`checkbox`	A toggle checkbox
`switch`	A toggle switch

4. Styles

style is the visual formatting record:

Field	Values
`bold`, `italic`, `underline`, `strikethrough`	booleans
`textColor`, `backgroundColor`	CSS color strings
`horizontalAlign`	`left` / `center` / `right`
`verticalAlign`	`top` / `middle` / `bottom`
`wrapText`	boolean
`borderTop` / `borderRight` / `borderBottom` / `borderLeft`	CSS border strings

Styles compose: bold, italic, and underline are independent toggles.

5. Conditional Formats

conditionalFormats is a list of value-driven style overrides. Each entry has an operator, its params, an optional scope, and the style to apply when it matches.

Operators:

greaterThan   lessThan   greaterThanOrEqual   lessThanOrEqual
equal         notEqual   between              notBetween
isEmpty       isNotEmpty textContains         textNotContains

A scope ({ kind: "cell" | "range" | "column", range?, column? }) lets a rule defined on one anchor apply across a region.

Conceptually, "color the cell red when the value is negative" is one conditionalFormats entry with operator: "lessThan", params: { value: 0 }, and style: { backgroundColor: "#fde2e1" }.

6. Inline Visualizations

visualizations render lightweight in-cell graphics. Each has a kind and an optional scope/id:

Kind	Renders
`colorScale`	Heat-map fill between `minColor`/`midColor`/`maxColor`
`progressBar`	A filled bar from `min` to `max`
`relativeBar`	A signed bar (positive/negative fill, optional zero baseline)
`badge`	A labeled badge chosen by per-rule operators
`sparkline`	A `line` / `bar` / `winLoss` micro-chart over a `source` range

7. Data Validation

validation constrains what a human may type into an editable cell. It does not affect computed values.

Validation can also be declared in source with a trailing VALIDATE clause — see presentation.md. A declared clause on an input cell compiles to this same metadata; on a computed cell it is a static assertion the compiler checks instead.

Field	Meaning
`type`	`"list"`, `"range"`, `"regex"`, or `"custom"`
`params`	Type-specific parameters (allowed list, min/max, pattern, …)
`allowBlank`	Whether an empty entry is permitted
`inputTitle` / `inputMessage`	Hint shown while editing
`errorTitle` / `errorMessage`	Message shown on a rejected entry

This mirrors Excel data validation and round-trips through xlsx import/export.

8. Comments, Rich Text, Hyperlinks, And Merges

comment — { text, richText?, editAs? }. A note attached to the cell. Model-level threaded comments are separate from cell notes.
richText — an array of { text, style } runs for mixed styling within a single cell.
hyperlink — { target, tooltip?, display? }.
merge — { rowspan, colspan } for a merged region anchored at the cell.

9. How Metadata Is Set And Read

Use source declarations for presentation contracts that should travel with the model: per-cell and type-tag FORMAT policies, input VALIDATE contracts, and ## documentation notes. The full style, conditional-formatting, visualization, merge, hyperlink, rich-text, and comment records remain document state set through the UI, product APIs, or import/export flows.

UI/API edits occupy the override layer above source declarations. In a rule, RESET FORMAT cell removes that override and reveals the declared format again. See Declared Presentation for the complete precedence order.

Excel import reads number formats, fonts, fills, borders, alignment, validation, hyperlinks, rich text, and comments into cell metadata. Excel export writes those details back out when the target format supports them.

Metadata patches merge: a partial update overlays the existing record field by field (styles merge key by key), so you can set a single property without resending the whole record.

10. Relationship To Type Tags

Type tags (A1 is currency = …) and cell metadata overlap but are distinct:

Type tags live in the model source and carry semantic meaning that drives validation and downstream consumers. They are part of the computed value's identity. See reference.md.
Cell metadata is the presentation/input layer. Most fields are set out of band; FORMAT, VALIDATE, and ## notes provide the source-declared subset. A currency tag suggests a currency number format, but the resolved rendering is governed by the presentation layers.

Use a type tag to say "this value is money"; use numberFormat to say "render it as $#,##0.00".

11. See Also

reference.md — type tags vs metadata.
presentation.md — source-declared formats, validation, notes, and override precedence.
functions.md — TEXT and in-formula formatting.