FP&A Practice Practical writing on financial planning, models as code, and AI agents
~/fml

Financial Modeling Language

FML is a declarative, human-readable source form for financial planning models — variables, dimensions, links and formulas as plain text files that round-trip losslessly with a live planning platform.

Financial Modeling Language (FML) is the source form for a financial planning model: the model's variables, dimension links, and formulas declared as plain text instead of trapped as clicks inside a tool. A .fml file states a variable's business grain, its links to other dimensions, and the formula that computes it — nothing else lives outside the file. This is model as code: the file is the model, and the planning platform is the runtime that executes it.

A revenue module, complete
variables/revenue.fml
# dimensions need no declaration — naming one in a grain is enough:
# Clients, SKUs, Brands, Years, Months
 
# relations — the FK graph that does the roll-ups
link SKUs -> Brands

# variables — each declares its grain, then its formula

"Quantity IN"    { Clients, SKUs, Years, Months }
"Unit Price IN"  { SKUs, Years, Months }
"Revenue OUT"    { Clients, SKUs, Years, Months }
                 = "Quantity IN" * "Unit Price IN"   @readonly
A two-year three-statement plan counted both ways: the generated Excel workbook holds 2,025 formulas across 57,989 referenced cells, and the FML model that produced it is 17 expressions. The animation goes on to show the profit and loss sheet as ordinary numbers, then the same sheet with every cell revealed as a formula — subtotals included — then two of those 17 expressions as FML source.
One .fml file, 17 expressions long, is the whole of a two-year three-statement plan. Excel says the same thing in 2,025 formulas reaching 57,989 cells. Lengthen the plan to four years and Excel is at 3,975; the file is unchanged.

The generator that wrote it runs in your browser: change the chart of accounts or the horizon and it rewrites both sides, then hands you the .fml and the .xlsx to keep.

Why it exists

Each of these traces back to the same gap: the model has no source form. FML closes it directly, one pair at a time:

No diff
Reviewable diffs — a model change reads like a code change, before it lands.
No history of why
Versioned reasons — the commit message carries the decision, next to the change itself.
No tests
Pinned regression totals — last quarter's reconciled numbers, checked before a refactor.
Invisible to AI agents
Agents read the model and propose changes as diffs, under human review.

The precedent

FML is not a novel idea — it's the same "as code" pattern that already played out, on schedule, in every other engineering discipline:

Discipline Its "as code" moment Since
Infrastructure Terraform — servers and networks declared in text, applied by plan 2014
Data transformation dbt — pipelines as versioned SQL, tested in CI 2016
BI semantics LookML — the metric layer as reviewable code 2013
BI semantics, mainstream Power BI TMDL — semantic models as git-diffable text 2024
Financial planning — still clicking — ?
A model change, as your team would actually review it
git diff · variables/revenue.fml
  "Revenue OUT" { Clients, SKUs, Years, Months }-     = "Quantity IN" * "Unit Price IN"+     = "Quantity IN" * "Unit Price IN" * (1 - "Discount % IN")+ # CR-142: contract discounts move from post-hoc adjustment into the model

That diff is a review, an audit trail, and an explanation — in six lines. Try producing any one of the three from screenshots.

FAQ

Is FML a programming language?
No — it's the declarative statements finance already thinks in (Revenue = Quantity × Price, at a stated grain), not a general-purpose language. Reading it matters far more than writing it.
Does the planning UI go away?
No. The grid, the sheets, and the drill-downs all stay exactly as they are. FML is the record underneath what you click — not a replacement for the planner’s experience.
What lives in a .fml file?
A variable's business grain, its links to other dimensions, the formula that computes it, and directives like @readonly that describe how a value behaves — plus the harness: the business context attached to the numbers, from the assumptions behind a target to the reason a driver changed, so an AI reading the model can interpret the figures, not just recompute them.
Where is the full specification?
FML 1.0 is published as a public git repository: the grammar, the evaluation rules, the function reference and the modelling guide, versioned, so the language has one citable source that a diff can change rather than a description spread across articles. It comes with conformance tests an engine can run. Where this page and the specification differ, the specification is the reference. FML 1.0 on GitHub.
How do AI agents use FML?
An agent reads the whole model as text, proposes a change as a diff, validates it against the dimension graph before anything touches the live system, and a human approves before it lands.
Who builds FML?
FML is the language behind Farseer models — farseer.com — introduced and documented on this site by Farseer's co-founder.
Read the essay → See it in articles About the author