Cell metadata

Cell Metadata

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.

Metadata is not part of .grid formula source. Formulas compute values; metadata decides how those values look and what inputs are accepted. In Grid it is document state: set it through the UI, import/export flows, or product APIs rather than through formula syntax.

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

Setting metadata never changes the cell's computed value, and clearing it never affects results — it is purely presentation and input policy.

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

Because metadata is document state, set it through the UI or import/export flows rather than the formula language.

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 set out of band. A currency tag suggests a currency number format, but the actual rendering is governed by numberFormat.

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

11. See Also