Skip to content
EN FR

ADR: DOM as an equivalence boundary

Documentation status: architecture.

Problem

Declarative applications can be authored through more than one serialization. Textual similarity is a poor definition of equivalence because ordering, aliases and formatting can differ while the executable model is the same.

Decision

Define equivalence at the parsed declarative structure/DOM and runtime-significant contract, not at raw text. XML and YAML are authoring projections that converge before model execution.

Consequence

Migration and round-trip tooling must compare runtime-significant content. Tests should have syntax, grammar/DOM and Runtime levels rather than treating a successful text conversion as proof of semantic equivalence.

Validation

Paired examples and regression tests protect the common contract. If a construct cannot round-trip, classify the loss explicitly.