Kookerella-Ltd/Kookerella.FsOpenXmlDsl

A typesafe F# DSL for building Excel workbooks, interpreted into calls against the
DocumentFormat.OpenXml SDK. The DSL is a plain
data model (records/DUs with structural equality) — the interpreter (Writer) compiles it
to OOXML, and the reverse transform (Reader) parses an existing .xlsx back into the
same DSL.
See MAPPING.md for exactly which SpreadsheetML features map 1:1, which are
approximated, and which aren't modeled yet.
**This round-trips in both directions**, which most Excel libraries (EPPlus, ClosedXML,
NPOI, ...) don't: they give you an imperative API to build a workbook from scratch or mutate
an existing one, but no way to turn an *existing* file back into readable source. Here,
Reader parses a real .xlsx/.xlsm back into the same DSL, and Workbook.generateScript
(F#) / CsCodeGen.Generate (C#) go one step further and render that model back out as a
self-contained script that rebuilds an equivalent file - a decompiler for spreadsheets, not
just a writer. Two more surfaces, Xml.ofWorkbook/Xml.toWorkbook (see "## XML"
below) and Json.ofWorkbook/Json.toWorkbook (see "## JSON" below), do the same
translation to/from plain XML or JSON against a real schema - for a caller who'd rather
generate or consume data than write code at all, e.g. an XSLT pipeline producing a report.
Kookerella.FsOpenXmlDsl.Mcp exposes all four directions as MCP tools
(generate_fsharp_script/generate_csharp_script/generate_xml/create_workbook_from_xml/
generate_json/create_workbook_from_json) for an AI agent, and as fsopenxmldsl-mcp
convert/build CLI commands for anyone else - try it on any spreadsheet you already have,
no code required:
Don't have .NET installed? Download a self-contained build for your platform from the
Releases page - no
install required.
Demos
Full worked examples of the decompile-then-extend workflow above - reverse-engineering
the same invoice template into C#, F#, an XSLT transform, and a plain JSON-generation
script, each wired up to real data and real tests proving the result stays schema-valid -
live in a companion repo:
Kookerella.Demo.DecompileToSource.
Layout
- src/Kookerella.FsOpenXmlDsl — the library.
- Reference.fs — CellRef and "A1"-style address conversions.
- Styles.fs — cell formatting: Color, FontStyle, FillStyle, BorderStyle,
AlignmentStyle, NumberFormat, CellProtection, CellStyle.
- Validation.fs — conditional formatting and data validation: ComparisonOperator
(shared by both), ConditionalFormatRule, ValidationKind, ValidationAlert, and the
ConditionalFormatEntry/DataValidationEntry records stored on Worksheet.
- Hyperlinks.fs — HyperlinkTarget (external URL/mailto: vs. internal same-workbook
reference) and the HyperlinkEntry record stored on Worksheet.
- Comments.fs — CommentEntry (classic cell comments, i.e. current Excel's "Notes" -
see MAPPING.md for the modern threaded-comments gap).
- Protection.fs — SheetProtection, the sheet-level protection flags stored on
Worksheet (pairs with CellStyle.Protection for per-cell locking), and
WorkbookProtection, the workbook-level structure/window protection flags stored on
Workbook.
- DefinedNames.fs — DefinedNameScope/DefinedNameEntry, stored on Workbook rather
than Worksheet - the one DSL concept that's genuinely workbook-level.
- PageSetup.fs — print settings: PageOrientation, PaperSize, PrintScaling,
PageMargins, and the PageSetup record stored on Worksheet.
- Tables.fs — Excel Tables: TableColumn, TableStyle, and the TableEntry record
stored as a list on Worksheet (a sheet can have several).
- Sparklines.fs — in-cell mini-charts: SparklineType, SparklineStyle,
SparklineCell, and the SparklineGroupEntry record stored as a list on Worksheet
(a sheet can have several independently-styled groups).
- Charts.fs — column/bar/line/pie charts: ChartType, ChartSeries, and the
ChartEntry record stored as a list on Worksheet (a sheet can have several).
- Images.fs — raster images: ImageFormat and the ImageEntry record (raw file
bytes plus a cell-range anchor) stored as a list on Worksheet.
- PivotTables.fs — PivotAggregation and the PivotTableEntry record (source range,
row/column/value fields, an anchor cell) stored as a list on Worksheet.
- Model.fs — CellValue, Cell, Worksheet, Workbook (including Workbook.
VbaProject, a macro-enabled workbook's raw vbaProject.bin bytes - see its own doc
comment; there's no dedicated Macros.fs since it's a single opaque field, not a new
type).
- Xml.fs / Xml.xsd — the XML surface: Xml.toWorkbook/Xml.ofWorkbook translate a