File Formats

Formulon focuses on modern Office Open XML and binary spreadsheet formats. The same calculation core sits behind every reader and writer, so the format layer is responsible for shape preservation and feature mapping rather than calculation behavior.

Glossary: OOXML

Office Open XML — the ISO/IEC 29500 family of zipped XML formats Microsoft Office uses, including .xlsx, .xlsm, and .xltx. Each .xlsx is a ZIP container whose parts (workbook, sheets, styles, shared strings, relationships, …) describe the document.

Glossary: passthrough part

A workbook part that Formulon parses just enough to preserve on save without claiming semantic ownership. The bytes survive a recalculation round-trip even when the engine does not evaluate the feature.

XLSX

The OOXML reader/writer handles:

• workbook parts and relationships,
• worksheets and their cells, formulas, and cached values,
• styles, number formats, fonts, fills, borders, themes,
• shared strings,
• tables and defined names,
• comments and threaded comments,
• hyperlinks,
• merges,
• data validations,
• conditional formatting,
• pivot tables and pivot caches,
• external links,
• protection metadata,
• sheet views, freeze panes, hidden tabs,
• per-row / per-column overrides.

Caching behavior

On load, formula cells keep both the formula text and the cached value found in the file. After recalc(), the cached values are replaced with the engine's computed values; on save, the file contains coherent formula / value pairs.

XLSB

The binary workbook path exists for workflows that need MS-XLSB reading and writing while keeping the same calculation model. As of v0.9.3, styles (BrtFmt/BrtXF), workbook-scope defined names (including future-function and LET formulas), cross-sheet 3-D references, and dynamic-array spill formulas (BrtArrFmla) all round-trip through XLSB — several of these previously produced .xlsb files that real Excel could not open. Array-constant literals remain limited to numeric elements: string, boolean, and error array-constant elements are recognized but not decoded, and are surfaced as an explicit error rather than silently miscoded.

XLSB feature	Before v0.9.3	v0.9.3+
Styles (BrtFmt / BrtXF)	limited	round-trips
Cross-sheet 3-D references	limited	round-trips
Workbook-scope names, future functions, LET	limited	round-trips
Dynamic-array spill formulas (BrtArrFmla)	limited	round-trips
Array-constant literals	numeric elements only	still numeric elements only

Conditional formatting, pivot tables, comments, and data validation remain OOXML-only — the XLSB reader/writer does not have record handling for those parts, regardless of version. Round-tripping a workbook that uses them through XLSB drops the feature rather than erroring; keep those workbooks on XLSX if you need the feature preserved.

Saving is explicit about container format: saveEx() / save_ex() take a WorkbookFormat to choose XLSB over XLSX, and the CLI derives the same choice from the -o path's extension (-o out.xlsb writes MS-XLSB; anything else writes OOXML). Loading, in contrast, is content-sniffed: loadBytes() / Workbook.load() detect XLSX vs XLSB from the bytes themselves (ZIP signature vs BIFF12 record stream), not from a file name, so a .xlsb payload loads correctly even without a matching extension.

What is preserved vs. evaluated

Input

*.xlsx / *.xlsb bytes in

↓

Read

Reader

↓

Evaluated partscells · formulas · defined names · tables · CF subset

Passthrough partscharts · drawings · form controls · VBA

↓

Engine recalc

Preserved as bytes

↓

Write

Writer

↓

Output

*.xlsx / *.xlsb bytes out

Feature	Read	Recalculate	Write
Formulas in cells	yes	yes	yes
Styles / number formats	yes	n/a	yes
Defined names / tables	yes	yes (resolved as references)	yes
Conditional formatting	yes	partial (evaluate subset)	yes
Pivot tables	layout / cache	no	yes
Charts	parts preserved	no	yes
Form controls / drawings	passthrough	no	yes
VBA project	passthrough	never	yes

VBA is preserved, not run

Workbooks containing VBA can round-trip through Formulon, but macros are never executed. Calculations that depend on macro-side state will diverge from Excel.

Non-goals

• Legacy .xls (BIFF) read / write.
• CSV is supported only via simple ingestion; rich Excel CSV quoting edge cases are not the target.
• Live external connections (PowerQuery, OLE DB, Web).

Read next

• Lifecycle — how bytes become the workbook model.
• Operations — sheet, cell, and structure edits.
• Compatibility / File format support — read / write / preserve matrix.