Spreadsheet YAML Format Reference

The .spreadsheet.yaml format is a self-contained, human-readable spreadsheet format that includes data, column configuration, and styling in a single file.

Minimal Example

metadata:
  formatVersion: "1.0"

columns:
  - key: name
    title: Name
  - key: value
    title: Value

data:
  - name: Item A
    value: 100
  - name: Item B
    value: 200

Full Specification

Metadata Object

metadata:
  formatVersion: "1.0"       # Required
  generator: "claude-opus"   # Optional: tool that created this
  created: "2025-01-25T12:00:00Z"  # Optional
  updated: "2025-01-25T14:30:00Z"  # Optional

Columns Array

Each column definition:

columns:
  - key: category           # Required: maps to data keys
    title: "Category"       # Display header (defaults to key)
    type: text              # Column type (see below)
    width: 150              # Pixel width (default: 120)
    readOnly: true          # Prevent editing (default: false)
    align: left             # left, center, right (default: left)

  - key: amount
    title: "Amount"
    type: currency
    width: 120

  - key: remaining
    title: "Remaining"
    type: currency
    formula: "=B{row}-C{row}"  # Applied to each row

Column Types

Type Description Jspreadsheet Mapping
text Plain text (default) type: 'text'
numeric Numbers type: 'numeric'
currency Currency with $ formatting type: 'numeric', mask: '$#,##0.00'
percent Percentage with % type: 'numeric', mask: '0.00%'
date Date picker type: 'calendar'
dropdown Selection list type: 'dropdown', source: [...]
checkbox Boolean checkbox type: 'checkbox'
color Color picker type: 'color'
image Image URL type: 'image' 
columns:
  - key: status
    title: "Status"
    type: dropdown
    source:
      - "Not Started"
      - "In Progress"
      - "Complete"
    width: 120

Data Array

Data can be specified as objects (recommended) or arrays:

Object format (recommended):

data:
  - category: "Talent"
    budget: 50000
    spent: 12000

  - category: "Equipment"
    budget: 25000
    spent: 8000

Array format:

data:
  - ["Talent", 50000, 12000]
  - ["Equipment", 25000, 8000]

Row-Level Formulas

The formula field in column definitions uses {row} as a placeholder:

columns:
  - key: remaining
    title: "Remaining"
    type: currency
    formula: "=B{row}-C{row}"  # Becomes =B2-C2, =B3-C3, etc.

Conditional Styling (Future)

columns:
  - key: remaining
    title: "Remaining"
    type: currency
    formula: "=B{row}-C{row}"
    style:
      negative:
        color: "#ef4444"      # Red for negative values
        fontWeight: bold

Complete Example

# budget.spreadsheet.yaml
metadata:
  formatVersion: "1.0"
  generator: "claude-opus"
  created: "2025-01-25T12:00:00Z"

columns:
  - key: category
    title: "Category"
    type: text
    width: 150
    readOnly: true

  - key: budget
    title: "Budget"
    type: currency
    width: 120

  - key: spent
    title: "Spent"
    type: currency
    width: 120

  - key: remaining
    title: "Remaining"
    type: currency
    width: 120
    formula: "=B{row}-C{row}"

data:
  - category: "Talent"
    budget: 50000
    spent: 12000

  - category: "Equipment"
    budget: 25000
    spent: 8000

  - category: "Post-Production"
    budget: 15000
    spent: 0

  - category: "Marketing"
    budget: 10000
    spent: 2000

File Naming Convention

  • Use .spreadsheet.yaml or .spreadsheet.yml extension
  • Name should describe the content: budget.spreadsheet.yaml, inventory.spreadsheet.yaml
  • Store alongside related codex files or in a /data directory