export format

Calcillo documents can be exported as self-contained JSON files for backup, sharing, and interoperability.

File Format

File extension: .calcillo
Content type: application/vnd.cloudillo.calcillo+json
Format version: 1.0.0
Encoding: UTF-8 JSON

Envelope Structure

{
  "contentType": "application/vnd.cloudillo.calcillo+json",
  "appVersion": "0.1.0",
  "formatVersion": "1.0.0",
  "exportedAt": "2026-02-20T10:00:00.000Z",
  "data": {
    "meta": { ... },
    "sheetOrder": [ ... ],
    "sheets": { ... }
  }
}

Envelope Fields

Field	Type	Description
`contentType`	`string`	Always `"application/vnd.cloudillo.calcillo+json"`
`appVersion`	`string`	Calcillo version that created this export
`formatVersion`	`string`	Export format version (currently `"1.0.0"`)
`exportedAt`	`string`	ISO 8601 timestamp of export

Data Fields

Field	Type	Description
`meta`	`object`	Document metadata (name, initialized flag)
`sheetOrder`	`string[]`	Sheet IDs in tab order
`sheets`	`Record<string, SheetExport>`	All sheets keyed by `SheetId`

SheetExport Structure

Each sheet in the sheets map contains:

Field	Type	Description
`name`	`string`	Sheet name (plain text from `Y.Text.toString()`)
`rowOrder`	`string[]`	Row IDs in display order
`colOrder`	`string[]`	Column IDs in display order
`rows`	`Record<string, Record<string, Cell>>`	Nested: `rowId → colId → Cell`
`merges`	`Record<string, MergeInfo>`	Merge definitions keyed by composite key
`borders`	`Record<string, BorderInfo>`	Border definitions keyed by composite key
`hyperlinks`	`Record<string, HyperlinkInfo>`	Hyperlink definitions keyed by composite key
`validations`	`Record<string, ValidationRule>`	Validation rules keyed by validation ID
`conditionalFormats`	`ConditionalFormat[]`	Ordered conditional formatting rules
`hiddenRows`	`Record<string, boolean>`	Hidden row flags
`hiddenCols`	`Record<string, boolean>`	Hidden column flags
`rowHeights`	`Record<string, number>`	Custom row heights in pixels
`colWidths`	`Record<string, number>`	Custom column widths in pixels
`frozen`	`Record<string, string \| number>`	Freeze pane settings

Sheet names are plain text in exports

The name field contains a plain text string from Y.Text.toString(), not a Y.Text instance. For full-fidelity backup including concurrent edit state, use the Yjs binary encoding instead.

Numeric Precision

All numeric values are rounded to 3 decimal places in the export to produce cleaner output. Cell values retain their original precision.

Complete Example

A spreadsheet with 2 sheets. The first sheet has values, a formula, styling, a merge, and a border. The second sheet is a simple data table.

{
  "contentType": "application/vnd.cloudillo.calcillo+json",
  "appVersion": "0.1.0",
  "formatVersion": "1.0.0",
  "exportedAt": "2026-02-20T10:00:00.000Z",
  "data": {
    "meta": {
      "initialized": true,
      "name": "Q1 Sales Report"
    },
    "sheetOrder": ["aB3x_Qm7kL9p", "Xk2nR8vH_wYq"],
    "sheets": {
      "aB3x_Qm7kL9p": {
        "name": "Summary",
        "rowOrder": ["r_Hw5qT2m", "r_m4JfL1p", "r_Nz9cKvW", "r_Qp4rW9x"],
        "colOrder": ["cAb3x", "cXk2n", "cM4Jf", "cNz9c"],
        "rows": {
          "r_Hw5qT2m": {
            "cAb3x": {
              "v": "Product",
              "bl": 1,
              "bg": "#e3f2fd",
              "ht": 2
            },
            "cXk2n": {
              "v": "Q1",
              "bl": 1,
              "bg": "#e3f2fd",
              "ht": 2
            },
            "cM4Jf": {
              "v": "Q2",
              "bl": 1,
              "bg": "#e3f2fd",
              "ht": 2
            },
            "cNz9c": {
              "v": "Total",
              "bl": 1,
              "bg": "#e3f2fd",
              "ht": 2
            }
          },
          "r_m4JfL1p": {
            "cAb3x": { "v": "Widget A" },
            "cXk2n": {
              "v": 15000,
              "ct": { "t": "n", "fa": "$#,##0.00" }
            },
            "cM4Jf": {
              "v": 18500,
              "ct": { "t": "n", "fa": "$#,##0.00" }
            },
            "cNz9c": {
              "v": 33500,
              "f": "=B2+C2",
              "ct": { "t": "n", "fa": "$#,##0.00" },
              "bl": 1
            }
          },
          "r_Nz9cKvW": {
            "cAb3x": { "v": "Widget B" },
            "cXk2n": {
              "v": 22000,
              "ct": { "t": "n", "fa": "$#,##0.00" }
            },
            "cM4Jf": {
              "v": 19800,
              "ct": { "t": "n", "fa": "$#,##0.00" }
            },
            "cNz9c": {
              "v": 41800,
              "f": "=B3+C3",
              "ct": { "t": "n", "fa": "$#,##0.00" },
              "bl": 1
            }
          },
          "r_Qp4rW9x": {
            "cAb3x": {
              "v": "Grand Total",
              "bl": 1,
              "it": 1
            },
            "cNz9c": {
              "v": 75300,
              "f": "=D2+D3",
              "ct": { "t": "n", "fa": "$#,##0.00" },
              "bl": 1,
              "bg": "#fff9c4"
            }
          }
        },
        "merges": {
          "r_Qp4rW9x_cAb3x": {
            "startRow": "r_Qp4rW9x",
            "endRow": "r_Qp4rW9x",
            "startCol": "cAb3x",
            "endCol": "cM4Jf"
          }
        },
        "borders": {
          "r_Hw5qT2m_cAb3x": {
            "bottom": { "style": 2, "color": "#1565c0" }
          },
          "r_Hw5qT2m_cXk2n": {
            "bottom": { "style": 2, "color": "#1565c0" }
          },
          "r_Hw5qT2m_cM4Jf": {
            "bottom": { "style": 2, "color": "#1565c0" }
          },
          "r_Hw5qT2m_cNz9c": {
            "bottom": { "style": 2, "color": "#1565c0" }
          }
        },
        "hyperlinks": {},
        "validations": {},
        "conditionalFormats": [],
        "hiddenRows": {},
        "hiddenCols": {},
        "rowHeights": {},
        "colWidths": {
          "cAb3x": 150,
          "cXk2n": 120,
          "cM4Jf": 120,
          "cNz9c": 120
        },
        "frozen": {
          "type": "row",
          "rowIndex": 1
        }
      },
      "Xk2nR8vH_wYq": {
        "name": "Raw Data",
        "rowOrder": ["r_Jx8mP3q", "r_Vn4wK7r", "r_Bt6yH2s"],
        "colOrder": ["cPq7r", "cWm3s"],
        "rows": {
          "r_Jx8mP3q": {
            "cPq7r": { "v": "Date", "bl": 1 },
            "cWm3s": { "v": "Amount", "bl": 1 }
          },
          "r_Vn4wK7r": {
            "cPq7r": {
              "v": "2026-01-15",
              "ct": { "t": "t", "fa": "yyyy-mm-dd" }
            },
            "cWm3s": {
              "v": 5200,
              "ct": { "t": "n", "fa": "#,##0" }
            }
          },
          "r_Bt6yH2s": {
            "cPq7r": {
              "v": "2026-02-01",
              "ct": { "t": "t", "fa": "yyyy-mm-dd" }
            },
            "cWm3s": {
              "v": 7800,
              "ct": { "t": "n", "fa": "#,##0" }
            }
          }
        },
        "merges": {},
        "borders": {},
        "hyperlinks": {},
        "validations": {},
        "conditionalFormats": [],
        "hiddenRows": {},
        "hiddenCols": {},
        "rowHeights": {},
        "colWidths": {},
        "frozen": {}
      }
    }
  }
}

In this example:

Summary sheet (aB3x_Qm7kL9p):
- Header row with bold text, blue background, and centered alignment
- Product data with currency formatting ($#,##0.00)
- Formula cells computing totals (=B2+C2, =B3+C3, =D2+D3)
- “Grand Total” row with a merge spanning columns A-C and italic styling
- Medium blue bottom border on all header cells
- Custom column widths (150px for product name, 120px for data columns)
- Frozen first row (header stays visible while scrolling)
Raw Data sheet (Xk2nR8vH_wYq):
- Simple 2-column table with date and amount data
- Date cells with yyyy-mm-dd format, number cells with thousands separator
- No merges, borders, or custom sizing (all defaults)