GoKawiilXML is a Cheap DSL
March 13, 2026
Yesterday, the IRS announced the release of the project I’ve been engineering leading since this summer, its new Tax Withholding Estimator (TWE). Taxpayers enter in their income, expected deductions, and other relevant info to estimate what they’ll owe in taxes at the end of the year, and adjust the withholdings on their paycheck. It’s free, open source, and, in a major first for the IRS, open for public contributions.
TWE is full of exciting learnings about the field of public sector software. Being me, I’m going to start by writing about by far the driest one: XML.
(I am writing this in my personal capacity, based on the open source release, not in my position as a federal employee.)
XML is widely considered clunky at best, obsolete at worst. It evokes memories of SOAP configs and J2EE (it’s fine, even good, if those acronyms don’t mean anything to you). My experience with the Tax Withholding Estimator, however, has taught me that XML absolutely has a place in modern software development, and it should be considered a leading option for any cross-platform declarative specification.
TWE is a static site generated from two XML configurations. The first of these configs is the Fact Dictionary, our representation of the US Tax Code; the second will be the subject of a later blog post.
We use the Fact Graph, a logic engine, to calculate the taxpayer’s tax obligations (and their withholdings) based on the facts defined in the Fact Dictionary. The Fact Graph was originally built for IRS Direct File and now we use it for TWE. I’m going to introduce you to the Fact Graph the way that I was introduced to it: by fire example.
Put aside any preconceptions you might have about XML for a moment and ask yourself what this fact describes, and how well it describes it.
< Fact path =" /totalOwed "> < Derived > < Subtract > < Minuend > < Dependency path =" /totalTax "/> </ Minuend > < Subtrahends > < Dependency path =" /totalPayments "/> </ Subtrahends > </ Subtract > </ Derived > </ Fact >
... continue reading