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. A third surface, Xml.ofWorkbook/Xml.toWorkbook (see "## XML" below), does the same translation to/from plain XML against a real, embedded 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 three directions as MCP tools (generate_fsharp_script/generate_csharp_script/ generate_xml/create_workbook_from_xml) 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:

dotnet tool install -g Kookerella.FsOpenXmlDsl.Mcp
fsopenxmldsl-mcp convert your-file.xlsx --lang csharp

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 Workbook to/from an XElement tree, and Xml.schemaSet() loads the paired schema (embedded in the assembly as a resource) for validating either direction. See "## XML" below.
  • Builders.fs — ergonomic helpers: plain functional constructors (cellA1, ...) for the canonical model, plus the SheetItem/CellEntry types (each a single simple DU case with optional fields) and the sheet fold function - a small tree-shaped "AST for building a sheet" (rows of cells, plus sheet-level facts like column widths, merges, conditional formats, data validations, hyperlinks, comments, autofilter, and sheet protection) that mirrors how SpreadsheetML itself nests. SheetDsl is what you actually write against: cell/row/autoFilter/conditionalFormat/ dataValidation/hyperlink/comment members with real optional parameters (?col, ?style, ?index, the data validation alert fields, ?tooltip, ?author) - no builder objects, no separate "styled" function, no None-noise for the common case. (Protect is the one SheetItem case with no smart constructor - SheetProtection is a plain record you build the usual F# way, { SheetProtection.Default with ... }.)
  • Interpreter/StyleRegistry.fs — interns fonts/fills/borders/number formats into a shared OOXML stylesheet (internal).
  • Interpreter/ChartWriter.fs / ChartReader.fs — charts' own DSL ↔ DrawingML/ChartML translation, split out from Writer.fs/Reader.fs given how much larger that one feature's OOXML surface is than everything else combined (internal).
  • Interpreter/ImageWriter.fs / ImageReader.fs — images' own DSL ↔ DrawingML translation (internal).
  • Interpreter/DrawingWriter.fs / DrawingReader.fs — own the one DrawingsPart/ <drawing> relationship a worksheet gets when it has charts and/or images, since both features share that one drawing canvas rather than each managing their own (internal).
  • Interpreter/PivotTableWriter.fs / PivotTableReader.fs — pivot tables' own group-by
    • aggregate engine plus DSL ↔ OOXML translation (pivotCacheDefinition/ pivotCacheRecords/pivotTableDefinition), split out from Writer.fs/Reader.fs the same way charts and images are (internal).
  • Interpreter/Writer.fs — DSL → OOXML (internal).
  • Interpreter/Reader.fs — OOXML → DSL, the reverse transform (internal).
  • Interpreter/CodeGen.fs — DSL → F# source text: renders a Workbook back out as a self-contained .fsx script that rebuilds an equivalent file when run (internal).
  • Api.fs — the public Workbook.save / saveToStream / load / loadFromStream / generateScript entry points.
• tests/Kookerella.FsOpenXmlDsl.Tests — one test per feature, each validating the produced file against the OOXML schema (DocumentFormat.OpenXml.Validation.OpenXmlValidator) and asserting an exact round trip back through the DSL. Each test also writes the workbook it builds to Examples/<test name>/output.xlsx (checked into the repo), so every feature has a real, openable .xlsx demonstrating it - a browsable gallery, not just assertions. Each scenario also gets an Examples/<test name>/script.fsx - see "Regenerating a file as F# source" below - which a separate, slower Category=Slow test group actually executes via dotnet fsi and verifies against the committed .xlsx, and an Examples/<test name>/workbook.xml - the same workbook through Xml.ofWorkbook, validated against Xml.xsd at generation time (see "## XML" below) - so one folder always has three views of the same example: the real file, the F# source that rebuilds it, and the XML that also rebuilds it. Assets/ holds the one test fixture too large to inline as a base64 literal like every other binary fixture in Tests.fs - a real vbaProject.bin extracted from a workbook actually saved by Excel, used by the macro example.
• samples/Kookerella.FsOpenXmlDsl.Sample — a small console app that builds a workbook, saves it, and reads it back.
• src/Kookerella.CsOpenXmlDsl — an idiomatic, immutable, fluent C# wrapper over this library, for callers who'd rather not touch F# discriminated unions/option types directly. Now covers every feature this library models at the worksheet/workbook level - see its own README for scope and an example. tests/Kookerella.CsOpenXmlDsl.Tests is its own C# xUnit suite, exercising the wrapper the way a real C# caller would rather than reusing the F# test project.
• src/Kookerella.FsOpenXmlDsl.Mcp — a local MCP (Model Context Protocol) server exposing this library's read/write/code-generation/XML capabilities as tools any MCP-compatible AI agent can call directly, and the same conversion capability as plain fsopenxmldsl-mcp convert/build CLI commands for anyone not going through an MCP client - see its own README for the tool list and how to configure it.

Quick start

open Kookerella.FsOpenXmlDsl
open type Kookerella.FsOpenXmlDsl.SheetDsl

let headerStyle =
    { CellStyle.Default with
        Font = Some { FontStyle.Default with Bold = true }
        Fill = Some { Color = Rgb(220uy, 220uy, 220uy) } }

Read the full README on GitHub →