Browse documentation
Docs/Language

Declared Presentation — FORMAT, VALIDATE, ## notes

A model's meaning lives in its formulas; how a value should look, what writes it accepts, and why it exists are usually scattered across UI state. Declared presentation brings all three next…

guideGrid 0.65.0Candidate docsCanonical contract

Watch it in Grid

See the concept in Grid.

Use the film for the product interaction and this article for the complete contract and reference detail.

Declared Presentation — FORMAT, VALIDATE, ## notes

A model's meaning lives in its formulas; how a value should look, what writes it accepts, and why it exists are usually scattered across UI state. Declared presentation brings all three next to the cell, in source:

## Quarterly revenue, gross of returns.
input revenue is currency = 100000
  FORMAT "$#,##0.00"
  VALIDATE BETWEEN 0 AND 10000000 MESSAGE "Revenue must be a positive dollar amount."

Clauses trail the declaration — inline or on directly following indented lines. They are declarations, not statements: the cell's formula stays exactly what it was.

Layering

Presentation resolves through four layers, weakest to strongest:

tag-implied default          a currency tag suggests currency rendering
  < tag policy               top-level FORMAT <tag> <expr>
    < declared per-cell      trailing FORMAT/VALIDATE clause, ## note
      < override layer       rule FORMAT actions + UI/API edits

RESET FORMAT x (a rule action) clears the override layer and drops back to the declared layer. Overridden cells report their provenance ("overridden (declared: …)") so a declared format is never silently lost.

Doc notes — ##

A ## line documents the next declaration; a trailing ## documents its own line:

## Discount applied before tax.
## Negotiated annually with the vendor.
discount = 0.15

tax_rate = 0.0875   ## City + state combined.

A blank line detaches a ## block, so decorative comment banners stay inert. Notes ride module metadata into the UI (cell inspection, tooltips) — they are documentation, not evaluated content.

FORMAT

Three placements, one vocabulary (spreadsheet format patterns):

price = 19.99 FORMAT "$#,##0.00"       # per-cell declaration

FORMAT percentage "0.0%"               # tag policy: every percentage-tagged cell

WHEN audit_mode THEN
  FORMAT price "$#,##0.0000"           # dynamic override from a rule
END

Format operands are expressions: FORMAT IF(compact_view, "$#,##0,,\"M\"", "$#,##0.00") re-derives when its inputs change. Tag policies resolve most-specific-first through the type lattice, so a USD policy beats a currency policy beats a number one.

VALIDATE

The clause vocabulary reuses the language's predicate keywords with the subject implicit:

input qty    is integer = 1        VALIDATE BETWEEN 1 AND 100
input qty2   is integer = 1        VALIDATE 1..100          # sugar for BETWEEN
input margin is percentage = 5pct  VALIDATE >= 0
input region = "EMEA"              VALIDATE IN ["EMEA", "AMER", "APAC"]
input invoice = ""                 VALIDATE LIKE "INV-%"
input code   = ""                  VALIDATE STARTS WITH "GRID-"

Accepted clause heads: the comparisons (=, <>, <, <=, >, >=), BETWEEN … AND … (and the lo..hi sugar), IN, LIKE / ILIKE, STARTS WITH, ENDS WITH, CONTAINS. An optional MESSAGE "…" supplies the rejection text. Bounds are expressions — VALIDATE 1..max_qty re-derives when max_qty changes.

VALIDATE means one of two things depending on where it sits:

On an input cell: a write contract

Every write surface — the grid UI and the model-binding ABI, so API and connector writes too — checks the incoming value (after type-tag coercion) against the clause. A rejected write returns the violation and leaves the cell unchanged. The contract gates writes only; changing a bound later does not retro-invalidate a stored value.

On a computed cell: a static assertion

The compiler's interval analysis propagates value ranges through formulas and discharges the assertion at compile time:

input x = 0 VALIDATE 0..1
y = x / (x + 1) VALIDATE 0..1    # proven — recorded in module metadata
z = x + 2      VALIDATE 0..1    # GRID_VALIDATE_UNSATISFIABLE: can never hold
w = x * 3      VALIDATE 0..1    # GRID_VALIDATE_UNVERIFIED: not provable

An input's write contract seeds the range other formulas observe — that is what lets y above be proven outright. Refuted assertions are warnings by default and hard errors under strict (see reference §5.4); unverified ones stay warnings, an honest signal that nothing checks the assertion at runtime.

Where clauses may not appear

Compound assignments (+=), graph bindings, and table bindings do not take presentation clauses — declare them where the cell is defined.

See also