At what point does a separately parsed external notation beat one embedded in the host language for a configuration surface many teams edit?

## What the embedded form is free-riding on A notation written inside the host language is ordinary source text, and that single fact hands it a toolchain nobody had to build. - The **host compiler** checks whatever the notation's shapes express, during the build, with no parser written. - The **editor** gives completion, navigation, rename and usage search wherever the words are real declarations. - **Packaging and distribution** are the host's: the vocabulary ships as a library with a version. - **Debugging and profiling** work, because the configuration is made of ordinary calls. - **Refactoring** across configurations is refactoring across source, which existing tools already do. Everything below is a threshold at which that free ride is worth giving up. Nothing below is a reason to give it up casually; all of these costs come back as work. ## The thresholds 1. **The authors cannot build the program.** This is the decisive one. An embedded notation requires the host toolchain, a compile, and an editor set up for the host language. If the people who must write and change configurations are outside that — a different discipline, a different team, an operator at a console — the embedded form is not merely awkward for them; it is unavailable. 2. **The text must change without rebuilding.** Embedded notation is source: changing a value is a code change, which means a build, a review, a package and a deploy. If configuration must change on a shorter cycle than the program ships on, it has to live as data the program reads, not as source the program is compiled from. 3. **More than one runtime must read it.** An embedded vocabulary is bound to its host. The moment a second implementation, written against a different runtime, must read the same configuration, only a separate text with a defined grammar can serve both. 4. **The vocabulary must be strictly limited.** An embedded notation inherits everything the host can express: an author can reach outside the vocabulary and run arbitrary computation, because the block is just code. A separate grammar permits only what it permits, which matters when the text is reviewed, sandboxed, or authored by people whose mistakes must be bounded. 5. **The failure and editing experience must be owned end to end.** With a separate notation you control positions, messages and completion entirely; embedded, you share them with a host compiler that reports in its own vocabulary. This alone rarely justifies the move, but it compounds with the others. ## What you buy when you leave the host | Piece | Embedded | Separately parsed | |---|---|---| | Grammar and parser | the host's | yours to write and maintain | | Validation of meaning, not just shape | partly the host's types | yours entirely | | Editor support | inherited | yours, per editor | | Versioning and compatibility | library versioning | a policy for text already written | | Evaluation | ordinary calls | a defined evaluator with its own semantics | | Debugging a wrong configuration | host tools | whatever you provide | The common estimating error is to price only the parser. The parser is the small part. The long-lived costs are the validator, the editor support and the compatibility policy for configurations written last year against a vocabulary that has since grown. ## The option in between Before inventing a grammar, consider **a plain data format with a published schema**. It gives most of what the first three thresholds ask for — authored by non-programmers, stored and diffed outside the program, readable by several runtimes, validated before use — without a hand-written parser, and editor support comes from the format's existing tooling rather than from you. It is a worse fit when the configuration is genuinely structured like a language, with references and composition that a flat schema expresses awkwardly. That is the point where a real grammar starts to earn its keep. ## How a lead frames the bet The decision is not about elegance; it is about who is on the other end of the text and for how long. Ask, in order: who authors it, how often, and with what training; what cycle their changes must land on; who else must read the same text; what happens when it is wrong, and who sees that first; how long a document written today must still load. Then state the staffing plainly — a separate notation is a small product with a compatibility obligation, not a weekend of parsing — and pick the least machinery that clears the thresholds you actually crossed. Teams routinely cross one threshold and buy the answer to all five; the discipline is to buy only what the threshold demanded.