Your team must publish a normative grammar for an annotation syntax that other teams will implement independently — what is the risk of making it an ordered-choice grammar?

## What you are actually publishing An ordered-choice grammar is a program. Its meaning is the behaviour of the recognizer it describes, and the language it defines is, by construction, *the set of inputs that recognizer accepts*. That is a strength for a single implementation and a liability for a standard, because a standard's job is to let several independent implementations agree without consulting each other. Compare what each side of the choice gives you: | You want to… | Ordered-choice grammar | A declarative rule set | |---|---|---| | Guarantee one interpretation | free, by construction | needs ambiguity to be resolved | | Describe the accepted set independently | not available | the rules are the description | | Compare two candidate specifications | not decidable in general | tooling exists for useful cases | | Execute the specification directly | yes | needs a generator | | Have overlap reported at build time | no | a deterministic generator reports conflicts | ## The four risks, concretely 1. **Conformance has no definition but behaviour.** "Implements the specification" means "agrees with this recognizer on every input", which is a statement about infinitely many inputs. Without a corpus, each team tests against its own reading and the disagreements surface as documents that parse differently in two places. 2. **Equivalence cannot be checked.** Deciding whether two such grammars accept the same inputs is not a question a tool can answer in general. So refactoring the normative grammar — splitting a rule, reordering for clarity — cannot be validated mechanically; it can only be tested. 3. **Ordering is invisible in review.** Moving one alternative above another is a one-line diff that no reviewer reads as semantic. It can make an alternative unreachable and silently shrink the accepted set, which is a compatibility break disguised as tidying. 4. **A specification error is silent.** There is no ambiguity report, so a mistake does not surface when the grammar is compiled. It surfaces when someone finally writes the input that discriminates between what you meant and what you wrote, usually after several implementations have shipped. ## Why 'cannot be ambiguous' is not 'cannot be wrong' This is the confusion the question is really testing. Determinism says every input has at most one interpretation *under this grammar*. It says nothing about whether that interpretation is the one the syntax was meant to have. A grammar with a shadowed alternative is perfectly deterministic and perfectly wrong: it assigns a definite, unintended meaning to a whole family of documents, and does so consistently enough that nobody notices for a long time. ## Making it work anyway The formalism is not disqualified — plenty of published syntaxes are specified this way. What changes is the process around it: - **Ship a conformance corpus as part of the normative text.** Inputs paired with expected trees, including one input per alternative and one per boundary case. This, not the rules, is what implementations are tested against. - **Forbid overlapping alternatives by convention** where you can, so the order is not load-bearing. If one alternative is a prefix of another, require an explicit boundary predicate rather than relying on position. - **Treat alternative order as frozen API.** Any reordering goes through the same review as a change to the accepted set, because that is what it is. - **Version the grammar and say what a version bump may do.** Adding an alternative at the end is usually safe; inserting one earlier is not, because it can capture inputs that previously fell through. - **Document the commitment rule in prose.** A reimplementer coming from a different parsing tradition will assume backtracking is unlimited, and will produce a parser that accepts strictly more than yours unless told otherwise. - **Keep the grammar small enough to read.** Its meaning is operational, so its size is the size of the specification a human must simulate in their head. ## The judgement call There is no universally right answer, which is what makes this a lead's decision. If the syntax is small, the implementations are few, and you can afford to publish and maintain a corpus, an executable unambiguous grammar is an excellent specification precisely because it is testable. If the syntax will be reimplemented by parties you do not control, in tools built on a different parsing approach, the inability to state the language independently of one recognizer is the thing that will eventually cost you — and the mitigation is to spend the effort on the corpus, since that is what the other teams will actually build against.