IR Schema

The gridwell IR (Intermediate Representation) is a JSON document that fully describes a table’s structure, content, and styling.

Design Principles

Declarative — describes what to render, not how
Flat where possible — uses indices/references, avoids deep nesting
Typed values — cells carry typed data alongside formatted text
Styling by reference — styles defined in a palette, referenced by ID
Span-aware — row/column spans are first-class with explicit placeholders
Versioned — ir_version allows future evolution

Top-Level Structure

{
  "ir_version": "1.0",
  "config": { },
  "styles": { },
  "header": { },
  "column_spec": [ ],
  "table": { },
  "footer": { },
  "extensions": { }
}

Field	Type	Required	Description
`ir_version`	string	Yes	Schema version (currently `"1.0"`)
`config`	object	Yes	Table-level configuration
`styles`	object	Yes	Style palette
`header`	object	No	Title, subtitle, extra header content
`column_spec`	array	Yes	Column definitions
`table`	object	Yes	Table data (thead + tbody)
`footer`	object	No	Footnotes and source notes
`extensions`	object	No	Arbitrary extension data

Content Nodes

Cell content is an array of content nodes:

Type	Fields	Description
`text`	`value`	Plain text
`styled_text`	`value`, `style_id`	Text with a style applied
`line_break`	—	Line break within cell
`footnote_mark`	`ref`, `mark_text`	Footnote reference mark
`image`	`src`, `alt`, `width`, `height`	Inline image
`raw`	`format`, `value`	Format-specific passthrough

Sections

Config — table-level configuration
Columns — column specification
Table Data — thead and tbody structure
Styles — style palette and references
Footer — footnotes and source notes
Validation — structural validation rules