Should I Build a DSL?

The default is no, and it should be stated first rather than reached reluctantly at the end. A language is not a feature; it is a product with an indefinite support obligation. The parser is a weekend. Diagnostics that name a line and a column, error recovery so one mistake does not hide the rest, a formatter, syntax highlighting, completion, a debugging story, documentation, a versioning policy and a migration path for existing programs are the actual project, and they never finish.

The reason to start from no is not pessimism. It is that the arguments for a DSL are vivid — here is the ugly code, here is the beautiful notation — and the arguments against are diffuse, arriving over the following three years in the form of a new engineer who cannot change a rule and an error message that says "unexpected token". A decision procedure that weighs a vivid benefit against a diffuse cost without a stated default will say yes almost every time.

The second reason is that most of the value people expect from a DSL comes from naming the domain concepts explicitly, and that is available from a library at a fraction of the cost. If the current code is unreadable because it does not name what it is doing, a language will not fix that; it will express the same confusion in a syntax nobody else knows.

Each question below has a way of answering it that does not rely on how you feel about the idea. Use those; the questions are easy to answer optimistically otherwise.

Is the domain stable? Look at the last year of commits to the code this would replace. If the *concepts* changed — not just the values, but what things are called and how they relate — the domain is still moving, and freezing it into a syntax guarantees a migration. Syntax is the hardest thing to change once programs exist in it, because every change is a change to somebody else's files.

Who reads these programs, and does syntax help them? Not who writes them — who reads them during an incident, six months from now. If the answer is "the same engineers who work in the host language", the notation gain is small and the tooling loss is large. If it is analysts, operators or domain experts who will not install a toolchain, that is the strongest single argument available for a DSL, and it is the one that justifies most of the successful ones.

Is the tooling budgeted, and who owns it? Name the person. Put the tooling in the same plan as the language, not in a follow-up ticket. If it cannot be staffed, the answer is no regardless of how good the design is, because an unowned language becomes infrastructure everyone depends on and nobody can change — the most expensive failure available here.

Could a library or a data format do it? Write the three hardest real examples as a library API and as schema-validated data. If the data version needs no conditional, no loop, no name binding and no reuse, it is data and it should stay data. If the library version reads acceptably to someone who did not design it, that is the answer.

The single strongest signal is an audience that is not the host language's programmers and cannot be. SQL exists because analysts needed to ask questions of data without writing programs. HCL exists because the people declaring infrastructure are not necessarily application developers. Shader languages exist because the hardware model is not the CPU's. In each case, "just use a library" was not available, because the readers were not in a position to use the host language at all.

The second is when the restriction buys a genuine guarantee. If making the language unable to loop means the configuration cannot hang, or making it unable to do I/O means a build is reproducible, or making the case set closed means the compiler can prove completeness over the domain, then the language is doing something a library in a general-purpose host cannot: it is *removing* capabilities, and a library cannot remove what the host provides.

The third is when the same specification must drive several outputs. One schema producing validation, serialisation, documentation and a client, from a single artifact that can be diffed and reviewed. That requires the program to exist as an inspectable artifact, and it is a real reason.

And a genuine fourth, less often stated: when the domain logic must be authored, reviewed and versioned independently of the application that runs it. A rules file that domain experts change and release on their own cadence is a different artifact from a code change, and making it a language is the honest expression of that.

The question is not binary, and treating it as binary is how teams end up at the expensive end. There is a ladder, and the honest recommendation is to climb it one rung at a time and stop as soon as the problem is solved.

Rung one: name the concepts in ordinary host code. Most "we need a DSL" conversations are actually about code that does not say what it is doing, and this rung solves a surprising number of them at zero cost.

Rung two: a schema-validated data format. If the programs are declarations with no control flow, this is the right size — the tooling comes from the schema ecosystem and the restriction is enforced by the format itself.

Rung three: an internal DSL. Domain notation, the host toolchain, and a wrong design decision is a deprecation rather than a migration.

Rung four: an external DSL with its tooling budgeted. This is where SQL, HCL and GraphQL live, and it is a real destination — just not the first one, and not one to arrive at by accident.

The trap is skipping rungs because rung four is the interesting engineering. It is, and that is exactly why the decision needs a stated default and a written-down set of criteria rather than an argument in a design meeting.

Saying yes is committing to a list, and the list should be in the proposal rather than discovered later. Diagnostics with a line, a column and a suggestion. Error recovery, so a file with two mistakes reports two. A formatter, because otherwise every review argues about layout. Editor support, which in practice means a language server. Documentation with examples. A versioning policy, including what happens to programs written against version one. A migration tool, or an explicit promise never to make a breaking change. And a debugging story, which is the item most often missing entirely — when a program in your language does the wrong thing, how does a user find out why?

It also commits you to saying no repeatedly. Every user will eventually ask for a conditional, then a loop, then a function, then a module system, and each request will be reasonable and supported by a real use case. Holding the restriction is the job, because the restrictions were the reason for the language. A DSL that grants every request becomes a general-purpose language with a worse debugger, which is [[configuration-languages]] in one sentence.

That is the honest bill. It is worth paying occasionally. It is not worth paying because the current code is ugly.