Domain-Specific Languages

The word sounds exotic and the examples are mundane. SQL is a DSL for relational queries. Regular expressions are a DSL for string patterns. Every build file is a program in a build language. CSS selectors are a query DSL over a document tree, CSS itself is a declarative styling language, and a shader is a program in a language that exists because general-purpose code cannot be scheduled across thousands of cores. Terraform HCL, Dockerfiles, Kubernetes manifests, cron expressions, glob patterns, printf format strings, jq filters, Prometheus's PromQL — all of them are languages, and most of them are used daily by people who would say they do not use DSLs.

What they share is not syntax; it is that each was created because expressing the same thing in a general-purpose language was worse *for the reader*, or because the restricted form permitted something the general form did not. Those are the only two reasons that hold up.

The most instructive one is SQL, because both reasons apply at once. It reads closer to a description of the desired result than to a procedure, and — decisively — because it does not specify how to compute the answer, an optimizer is free to choose. That freedom is why the same query gets faster when the data changes shape or the planner improves, with no edit. A hand-written procedural query in a general-purpose language would have fixed the plan at the moment it was written.

The common answer — "a DSL has its own syntax" — is wrong in both directions. Plenty of things with their own syntax are data formats rather than languages, and plenty of things with no syntax of their own are languages in every sense that matters. The line that holds up is about *analysis*: does the thing exist as an artifact that can be inspected, checked, transformed or planned before it runs?

A library call is executed. A DSL program is a value that can be read. When you write a query with an ORM query builder, the builder constructs an object; if that object is inspected, optimized and translated before anything runs, you have written a program in an internal DSL. If the calls simply execute one by one, you have called a library. That distinction is what determines whether the domain's knowledge can be applied to the program as a whole.

The practical test: can you write a program in it, look at that program without executing it, and say something useful about it? A checker that rejects a nonsensical combination, a planner that reorders it, a formatter that rewrites it, a diff that shows what will change. If yes, it is a language, whatever the syntax looks like. If no, it is an API — which is fine, and considerably cheaper, and usually the right answer.

Note what this test does *not* say. Turing-completeness is irrelevant; most good DSLs are deliberately not Turing-complete. Having a parser is irrelevant; an internal DSL borrows the host's. Being interpreted rather than compiled is irrelevant. Only the existence of an inspectable program is load-bearing.

It is tempting to describe a DSL by what it adds — nice notation, domain vocabulary. The durable value is usually in what it removes. A language that cannot loop cannot hang. A language with no I/O cannot have a hidden dependency. A language with no mutable state can be evaluated in parallel or in any order. A language with a closed set of cases can be checked for exhaustiveness over them.

Every entry in the table above is an instance. Regular expressions can be compiled to an automaton with a bounded per-character cost precisely because they cannot recurse — and the moment a regex dialect adds backreferences, that guarantee is gone and catastrophic backtracking becomes possible, which is the source of a whole genre of production incident. The restriction was not a limitation that got fixed; removing it removed the property.

This is why feature creep in a DSL is a technical problem and not just a taste problem. Each added feature is fine in isolation and each one potentially invalidates an assumption some component was relying on. Adding a conditional to a configuration format means it can no longer be validated statically. Adding a function to a build language means the dependency graph may no longer be computable without running the file. The end state is a general-purpose language with a hand-written parser, no debugger and one maintainer — and every language that got there arrived one reasonable feature at a time.

Everything above is the case for. The case against is that a language is not a feature, it is a product with an indefinite support obligation, and the parser is the small part of it. People who depend on a notation expect syntax highlighting, a formatter, error messages that name a line and a column, completion, a way to debug what a program did, documentation, and a story for what happens when the language changes. That list is [[dsl-tooling-cost]], and it is the reason [[should-i-build-a-dsl]] answers no by default.

The other cost is a second thing to learn. Every DSL in a codebase is a language a new engineer must acquire before they can change anything, and unlike the host language there is no book, no Stack Overflow and no model that has seen a million examples of it. A notation that saves its authors an hour a week and costs every reader a day of onboarding is a bad trade that never shows up in any measurement.

The honest summary is that DSLs are excellent where the domain is stable, the audience is not the host language's programmers, and someone owns the tooling — and a liability everywhere else. That is a narrow target, and the rest of this module is about aiming at it.