A platform team is deciding whether to build a new configuration language as an internal DSL embedded in their host language, or as an external DSL with its own grammar and parser. What factors should drive that decision, and what's a concrete failure mode of picking the wrong one?

## What the choice really turns on Choosing between an internal and an external DSL is fundamentally a decision about who the authors are and what guarantees the language must provide them, weighed against how much tooling investment the team can sustain. ## The first factor: who writes it The first factor is audience. - If the people writing DSL content are the same **developers** who build the surrounding system, an internal DSL lets them stay in one language, reuse their existing IDE, debugger, and package ecosystem, and move fluidly between DSL code and regular code. - If the authors are **non-programmers** - business analysts, operations staff, domain experts - an external DSL can offer a notation stripped of general-purpose-language noise (no generics, no exception types, no import statements) that's purpose-built for their mental model of the domain, which an internal DSL, still bound by host-language syntax, usually cannot achieve as cleanly. ## The second factor: safety and sandboxing The second factor is safety and sandboxing. An internal DSL is, at the end of the day, real code in a Turing-complete host language, executed with the full power and privileges of that language's runtime. If a requirement states that a malformed or malicious rule must never be able to read a file, open a socket, or loop forever, an internal DSL cannot guarantee that by construction - you would need to layer extra runtime sandboxing on top, which is easy to get subtly wrong. An external DSL's grammar, by contrast, can simply omit any production that would allow such operations, making them syntactically unreachable rather than merely discouraged by convention or code review. ## The third factor: tooling cost The third factor is tooling cost, and it cuts strongly toward internal DSLs for small or short-lived needs. Building an external DSL means owning, indefinitely: - a grammar and a parser; - error-recovery and message quality; - editor integration (syntax highlighting, autocomplete, validation); - a migration story for every future grammar change, since a grammar change is effectively a breaking change to every existing document written in the old grammar. An internal DSL gets almost all of this for free from the host language's existing compiler and IDE plugin, at the cost of being bound by that language's syntax and having host-language error messages leak through to DSL authors who may not understand them. ## Failure modes on both sides - **Scope mismatch, on the external side.** The most common failure mode on the external-DSL side is scope mismatch: a team builds a full grammar-and-parser stack for a configuration language used by a handful of developers who are already fluent in the host language and didn't need sandboxing at all. Two years later the grammar is under-documented, the hand-rolled parser produces unhelpful 'unexpected token' errors, nobody remembers its edge cases, and the team is spending more time maintaining this second undocumented language than they ever spent on the feature it configures. - **Scope creep, on the internal side.** The mirror-image failure mode on the internal-DSL side is scope creep in the other direction: a configuration DSL meant to be purely declarative gradually accretes real imperative logic - conditionals, loops, even network calls - because nothing in an internal DSL structurally prevents it, and what was meant to be a safe, inspectable configuration surface becomes a second, undisciplined programming environment embedded inside the first one, with none of the safety guarantees anyone assumed it had. ## Getting the call right A good real-world illustration of getting this right is the split between Gradle's build DSL and Terraform's HCL. Gradle deliberately chose internal DSLs (first Groovy, later Kotlin) because its authors are developers who benefit from full language power, an existing IDE, and access to the entire JVM ecosystem, and sandboxing build authors from arbitrary logic was never a hard requirement. Terraform, whose infrastructure-as-code files are meant to stay declarative, diff-friendly in code review, and statically analyzable by policy tools without executing arbitrary code, deliberately built HCL as a purpose-built external DSL instead - accepting the higher tooling investment in exchange for a language whose grammar itself forbids the imperative escape hatches an internal DSL could not rule out.