Informational draft
The draft document names the portable pieces of a structured merge contract: owners, matching, read fidelity, attachment, rendering, capabilities, repair, surfaces, and delegation.
The current document is an informational draft, not a formal standards-body specification or Internet Standard. It uses RFC-style vocabulary to make conformance expectations precise while the project validates the model through implementations and fixtures.
A .smrules file is a line-oriented declaration document for merge semantics. The draft source is maintained in structuredmerge-spec/MERGE_RULESET_INFORMATIONAL_DRAFT_02.md.
The contract format is intentionally small and deterministic: directives, comments, and blank lines in a stable ABNF-compatible syntax. The shared vocabularies (including `read` and `attach`) keep implementations aligned.
StructuredMerge standardizes the semantic vocabulary needed for independent engines to produce identical outcomes on identical inputs. Engines can choose different parser backends and internal algorithms.
Published inline
This copy is rendered from the same Markdown draft maintained in the structuredmerge-spec repository.
Intended status: Informational
Expires: N/A
This document defines a vocabulary and compact ruleset format for describing merge behavior for structured document languages. Existing standards work largely addresses patch transport and format-specific change application. It does not define a portable way to express structural matching, non-structural ownership, logical-owner preservation, layout preservation, repair-policy handling, reviewable unresolved outcomes, or merge-surface and delegation declarations across document families.
This document specifies:
The goal is not to standardize one universal merge algorithm for all languages. The goal is to standardize the terms and ruleset structure needed so merge engines written in different implementation languages can interpret the same merge contract.
This memo provides information for the Internet community. It does not specify an Internet standard of any kind.
Structured document formats such as YAML, JSON, TOML, XML, shell configuration files, dotenv files, Markdown, and type-signature formats often require merge behavior that is more semantics-aware than line-based diff/merge and more presentation-aware than patch application.
Across these formats, the same practical questions recur:
In many implementations, answers to those questions are encoded as implicit local code rather than explicit portable declarations. This document proposes a compact ruleset format for expressing those answers directly.
That same concern applies when one merge family supports multiple parser backends. Parser plurality is useful only if the backend choice does not make the family contract private or accidental. A family SHOULD therefore make backend ownership explicit and SHOULD validate the same family-facing behavior across its supported backends unless a backend-specific restriction is declared explicitly.
This draft also makes explicit a distinction that was only implicit in earlier work: a ruleset standardizes observable merge meaning, not one parser stack or one intermediate merge algorithm. A conforming implementation MAY use a native parser, a tree-sitter parser, a source-preserving parser, or a family-specific analysis substrate, provided that backend limitations, node-role handling, and rendering behavior remain visible at the declared contract boundary.
The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in RFC 2119 and RFC 8174 when, and only when, they appear in all capitals.
Existing patch specifications define ways to describe and apply changes to a document or resource. They do not define a common model for merge semantics across structured document languages, especially where:
As a result, merge behavior is repeatedly reimplemented in incompatible ways even when the conceptual model is substantially shared.
The same gap appears when a merge cannot or should not be finalized immediately. A tool may need to preserve reviewable unresolved state, hand it to another process or user-facing system, and later resume from the same merge context. Without common conceptual vocabulary for that handoff, systems tend to rely on implementation-local case numbering or positional coincidence rather than explicit semantic binding.
This document standardizes:
This document does not standardize:
This document also does not require any consumer to externalize unresolved runtime state. It only defines the conceptual vocabulary needed so that, when such state is exposed, tools can describe and evaluate it without depending on one implementation’s private terminology.
A syntax element that may own attached non-structural content such as comments or adjacent layout gaps.
Examples include:
A classification assigned to a syntax or analysis node for merge purposes.
Common node roles include:
structuraltokentriviacommentdelimiterseparatorvirtualerroropaqueA node role describes how a node participates in ownership, matching, attachment, rendering, and fallback behavior. It does not require all parser backends to expose identical node classes.
Portable rulesets MUST use virtual for parser-independent constructed nodes.
Implementations MAY still use local implementation terms internally, but the
portable ruleset boundary does not define compatibility aliases for them.
A node or owner whose internal children are not independently merged under the current ruleset.
Atomic treatment is a merge contract decision. It MAY be used because a syntax construct is semantically indivisible, because a backend cannot safely expose its children, or because the ruleset intentionally delegates that subtree to a different surface.
A named set of children under a structural owner that share ordering, matching, or merge policy.
Examples include:
Child groups allow a ruleset to express merge-relevant tree structure without standardizing one internal tree representation.
A structural identity value derived from a node, owner, or child group.
A signature MAY be used as a match key or as one component of a richer match key. It SHOULD be derived from declared observable syntax or semantic fields, not from backend-local memory identity or transient traversal order.
A merge-relevant artifact whose preservation or removal is governed by semantic rules other than ordinary structural presence.
Example: a Markdown link definition that SHOULD remain if references to it remain.
The identity used to determine whether source and destination owners correspond.
Examples include:
A consumer MAY expose additional match candidates that are not yet the sole normative match key in a given behavior profile, so long as the actual match rule remains explicit.
Consumers MAY also expose whether an accepted correspondence came from a baseline rule or from a declared refinement pass, so long as the distinction is descriptive rather than a hidden substitute for the normative match key.
A reproducible location identifier within an analyzed document that MAY be used as an observable matching surface.
Examples include JSON Pointer-style owner paths or normalized structural paths derived from syntax trees.
When a consumer uses stable path as part of a behavior profile, the path format and normalization rules SHOULD be explicit enough for cross-implementation conformance testing.
A declared parse or merge variant within a document family that changes observable acceptance or interpretation rules without changing the broader document family.
Examples include strict JSON versus JSON-with-comments handling, or other extension-controlled parse modes that share the same high-level merge family.
A grouped comment unit. Region kinds include:
preambleleadinginlinetrailingpostludeorphanA blank-line region between structural owners or at a document boundary that MAY carry ownership semantics.
The rule by which comments are obtained from the source representation.
The rule by which comments and layout gaps are attached to owners.
The rule that determines which syntax elements participate as merge-relevant owners.
A named declarative statement about a merge-relevant semantic surface, support boundary, limitation, divergence, or intentional non-support case in a ruleset.
A capability declaration may therefore be used to express either:
A behavioral class in which merged output is emitted according to the declarative ruleset contract, without requiring direct in-place mutation of native syntax-owned annotation or attachment structures.
This term is behavioral rather than architectural. Its internal realization is out of scope.
A derived summary of the merge-relevant behavior declared by a ruleset.
A feature profile typically summarizes:
The feature profile MAY be produced by tooling rather than written directly in the compact ruleset syntax.
When exposed, a feature profile is a normalized descriptive view of the declared contract. It is intended for inspection, conformance reporting, diagnostics, or feature negotiation. It is not itself the source of normative merge semantics; the ruleset remains the normative declaration.
A feature profile MAY additionally include derived classification metadata such as:
Such derived metadata SHOULD be computed only from declared ruleset meaning or explicitly documented normalization rules. It MUST NOT encode implementation-local heuristics as if they were ruleset semantics.
If the underlying ruleset omits optional directives because those surfaces are outside the declared merge contract, an exposed feature profile SHOULD preserve that omission rather than synthesize values. For example, it SHOULD not invent a comment family when comment_style is absent or a render family when render is absent.
Where an implementation supports aggregate conformance or capability reporting across families, it MAY additionally expose a default family context derived from a declared family feature profile. Such defaulting is appropriate only when the derived context does not introduce merge ambiguity or silently change merge semantics. An implementation that exposes such defaulting SHOULD also expose that assumption as a manifest-level diagnostic rather than silently omitting the undeclared context.
Nested delegated child operations MAY be discovered from parser-owned structure or from owned regions derived by family analysis. Markdown fenced code blocks and Ruby documentation/example surfaces are both instances of this broader pattern. In such cases, the transport SHOULD preserve:
Implementations MAY also offer an explicit context mode in which family contexts must be declared directly and derived defaults are not allowed. In that mode, missing contexts are configuration errors rather than recoverable defaults.
A merge-relevant region within a document that MAY be merged under a distinct sub-ruleset or delegated merge contract.
Examples include:
The source from which a merge surface is derived.
Surface ownership MAY come from:
Surface ownership is an observable identity boundary. It need not imply a single parser or AST representation.
A merge surface identified during family analysis rather than declared directly as a top-level document.
A discovered surface SHOULD expose:
A declarative rule describing whether and how a merge surface is handed to another merge contract.
Delegation policy is distinct from parser behavior. It describes observable merge responsibility, not a particular implementation call graph.
An execution unit created for a discovered child surface.
A delegated child operation preserves:
The delegated child-operation concept is transportable. It does not require a particular runtime session or inline recursion model.
A declarative rule describing how a consumer handles ambiguous, overlapping, or historically corrupted merge states that fall outside the ideal declarative ownership model.
Typical repair-policy outcomes include:
A canonicalized text form produced before or during analysis for the purpose of portable comparison, validation, structural matching, or conformance testing.
Normalized source is an observable behavior artifact. It is not necessarily the same as either the original input bytes or the final rendered output.
A constrained transformation applied before parser or matcher execution in order to realize a declared merge contract in a portable way.
Examples include comment stripping for a comment-tolerant dialect before handoff to a stricter native parser, or newline normalization before text-block analysis.
Preprocessing MAY be used by a consumer when its effect is part of the declared or documented observable contract. A consumer MUST NOT silently repair syntax that the declared contract says is invalid unless an explicit repair policy permits that behavior.
A lightweight extracted view produced by a parser backend before full family analysis or merge resolution.
Typical process-analysis outputs include:
Process analysis is especially useful for source-language families that need a portable ownership and matching baseline before richer AST-aware merge behavior is declared.
A concrete parser-backed implementation path used by one merge family.
Examples include:
A family backend is an implementation concern, but it may have observable capability or conformance consequences. A consumer MAY therefore expose backend identity and backend-limited conformance results without changing the family contract itself.
A family MAY also expose a backend-specific feature profile view for conformance or planning surfaces, so long as the view remains consistent with the family contract rather than leaking parser-internal detail.
Backend plurality is intentionally part of the model. A source or structured family MAY therefore validate the same fixture or ruleset corpus against multiple backend implementations side by side so long as each backend satisfies the same family-facing contract.
Backend hosting is a separate concern from backend plurality. Reusable
parser-framework integrations SHOULD live in tree-haver or its equivalent,
while parser-specific one-trick integrations MAY live directly in the
merge-family library that uses them. In both cases, the resulting backend MUST
still satisfy the same family-facing contract and shared diagnostic/result
shapes.
A stable identifier for a concrete family backend or backend capability class.
A backend reference is intended for diagnostics, conformance selection, feature profiles, and explicit backend requirements. It SHOULD be stable across releases unless the backend-facing behavior changes incompatibly.
A backend supplied by an implementation package that plugs into a family substrate while preserving the same family-facing merge contract.
Provider backends are especially useful when one language family has more than one viable parser or source-analysis stack. The provider boundary SHOULD expose normalized tree, diagnostic, source-span, and render-support information rather than parser-private objects alone.
When a provider internally retains parser-native objects for reparsing, incremental edit projection, source preservation, or backend-local rendering, those objects remain implementation detail. The portable surface is the normalized tree plus declared capabilities, diagnostics, and result metadata.
Parser-specific information that is useful to downstream provider-aware tools MAY be transported as namespaced metadata on normalized nodes or related sidecar records. Generic ruleset interpretation and portable merge behavior MUST NOT depend on metadata whose namespace is not part of the declared portable contract. Such metadata is an opaque transport surface unless a family profile explicitly standardizes its meaning.
Normalized tree nodes MAY therefore be progressively enhanced by parser
capability. Unsupported optional node features SHOULD be represented by stable
default values, null values, empty collections, or explicit unsupported-feature
markers rather than by requiring a second parser-native tree shape.
A provider backend that obtains syntax or semantic information from a parser native to the document language or to that language’s primary tooling ecosystem.
Native parser backends MAY expose richer language semantics than generic parser frameworks, but they MUST declare limitations that affect merge behavior, source retention, comment handling, or render fidelity.
A provider backend that retains enough original source structure to support fragment reuse, formatting preservation, or source-shaped rendering.
Source-preserving behavior may be complete, partial, or unavailable for a particular family. Consumers SHOULD report that capability explicitly when it is used for conformance planning or default-driver recommendation.
A conformance-case constraint that limits selection to a named family backend.
Backend requirements are evaluated at case-selection time alongside dialect and policy requirements. A consumer MUST NOT silently select a backend-limited case when a different backend is active. Backend requirements MAY be declared directly on a case or propagated through a manifest entry that plans such a case.
Parser-agnostic family logic shared by multiple backends for the same family.
A family substrate may normalize node kinds, owner paths, or merge-relevant structure before parser-specific merge code continues. A family MAY keep this substrate inside one merge library or expose it as a separate shared package when packaging, native dependency, or installability concerns make that split useful.
A family substrate MAY also host the primary tree-sitter-backed path for that family while sibling provider packages host optional native-parser variants.
A family-specific package that supplies one concrete backend while preserving the same family-facing contracts defined by the substrate.
The ability to preserve and reuse original source fragments associated with owners, nodes, child groups, or render surfaces.
Source fragment retention is distinct from semantic correctness. It is relevant to formatting preservation, reviewability, and default merge-driver suitability. This document names the concept but does not define one scoring formula.
The declared output-shaping approach used after merge resolution.
Examples include:
A render strategy MAY be more specific than a render family. The render family names the output surface; the render strategy describes how an implementation attempts to produce that surface.
A runtime merge outcome in which a consumer preserves one or more reviewable cases instead of collapsing immediately to one emitted result.
An unresolved outcome MAY arise from direct conflict, ambiguity, policy-required review, unsupported capability boundaries, or other situations where the consumer intentionally preserves choice for a caller or later review step.
An unresolved outcome MAY still carry a provisionally emitted result so long as the preserved review cases explicitly identify that provisional winner as a default pending review rather than as a silently final resolution.
An unresolved outcome MAY be completed within the producing runtime or resumed later through externalized review state if the consumer chooses to expose such a handoff surface.
An unresolved outcome is a runtime-facing state in this draft. It is not, by itself, a standard ruleset directive or a required persistence format.
A single reviewable item within an unresolved outcome.
A resolution case records the competing candidates, interpretations, or policy branches that remain open, together with a reason classification and any provisional default that would apply absent explicit review.
When a consumer exposes structured runtime state, a resolution case SHOULD be capable of identifying at least:
When a reviewable case offers acceptance of a synthesized or provisional default, implementations SHOULD expose that proposed value as structured data rather than only as prose. A host that resumes or renders review state should not need to parse a human-oriented message string to know what is being accepted.
When a reviewable case allows a caller to provide a structured replacement value, that decision payload SHOULD travel through the same replay-safe review surface rather than requiring a separate out-of-band override channel.
If an imported review decision requires structured payload data, a consumer SHOULD validate that payload before applying it. Missing or semantically mismatched payload MUST NOT be silently treated as a valid resolution.
When review requests expose multiple possible actions, implementations SHOULD export those actions as structured offers rather than as a bare string list, so hosts can determine whether additional payload is required before presenting or submitting a decision.
If a review action requires structured payload, the action offer SHOULD identify the payload kind explicitly rather than requiring the host to infer it from the action name alone.
When a consumer rejects one specific replayed review decision, it SHOULD expose the rejected request identity and action in structured diagnostic fields rather than only in diagnostic prose.
When a rejected or invalid review decision falls into a known machine-readable class, a consumer SHOULD also expose a structured diagnostic reason rather than forcing hosts to infer that reason from human-readable prose.
If the rejection or invalidity is specifically due to missing structured review payload, the consumer SHOULD expose the required payload kind on the diagnostic itself rather than only in the review action offer.
If the rejection or invalidity is specifically due to a family mismatch, the consumer SHOULD expose the expected and provided family identities on the diagnostic itself rather than only in prose.
When diagnostics carry review-specific structured metadata, implementations SHOULD prefer a nested review-detail object rather than continuing to grow the top-level diagnostic surface with review-only fields.
An opaque stable identifier for a resolution case that is intended to remain meaningful across recomputation of the same unresolved merge surface.
A review identity is a semantic binding concept, not a prescribed encoding. It is used to determine whether a saved review decision still refers to the same reviewable case after the merge state is recomputed.
A review identity is distinct from a runtime-local case number, presentation order, or storage offset. Those MAY be useful within one producing runtime but are not, by themselves, replay-safe semantic identifiers.
The minimum externally visible context needed to evaluate whether previously saved unresolved-review decisions still apply to a newly produced unresolved state.
Replay compatibility context MAY include source-version evidence, ruleset-version evidence, normalized input fingerprints, or other compatibility indicators. This document does not standardize the transport shape or exact fields. It standardizes only the concept that replay-safe review requires explicit compatibility evaluation rather than blind reassociation by local case identifier.
When a consumer exposes resumable review state, it MAY also expose host-policy hints describing whether the producing call was interactive-capable, whether strict explicit declarations were required, or similar caller-selected review constraints. Such hints are descriptive state, not transport or UI commands.
If a consumer accepts imported review decisions for replay, those decisions SHOULD be accompanied by replay-compatibility context. A consumer that cannot establish compatibility SHOULD reject the imported decisions explicitly rather than downgrading silently to best-effort positional reassociation.
When compatibility is established, a consumer SHOULD still evaluate whether each imported decision refers to a currently live review identity rather than assuming that every decision in a compatible bundle remains applicable.
Implementations MAY expose replay inputs as separate fields or as one replay bundle object so long as the observable replay-compatibility and replay-safety semantics remain unchanged.
If review state or replay bundles are externalized as JSON, implementations SHOULD preserve the normalized observable contract across serialization and deserialization rather than treating JSON export as an implementation-private debug dump.
When implementations externalize review state or replay bundles for transport, they SHOULD prefer an explicit kind-marked, versioned envelope over a bare payload with only out-of-band meaning. A consumer that receives an unexpected envelope kind or unsupported envelope version SHOULD reject that transport explicitly rather than treating it as best-effort compatible.
The externally visible reporting channel through which a consumer exposes unsupported capabilities, repair-policy activation, delegation failure, unresolved-outcome activation, or other declared-contract mismatches.
A diagnostic surface is a consumer-facing reporting concept. It is not, by itself, a separate ruleset directive or semantic axis unless some future extension explicitly declares one.
Capability classes describe which semantic surfaces, support boundaries, or declared limitations are part of the merge contract.
These classes are not limited to comments. They cover:
A ruleset consumer MUST recognize the capability vocabulary defined in this section and treat it as part of the declared contract vocabulary.
These capability classes describe the externally relevant merge contract. They do not standardize:
Not every ruleset will require every class. For example, a comment-free format such as strict JSON may rely on structural and layout declarations while never requiring comment-fidelity capabilities.
This document therefore includes comment-free formats within scope. The compact ruleset shape defined here still uses a uniform declaration model centered on read and attach, but that does not imply every ruleset depends on rich comment semantics.
In this model:
read directive selects among the read/write realization classes in Sections 6.3 through 6.5, andcapability directive may declare additional semantic surfaces or explicit support boundaries relevant to the ruleset contract.structural_onlyThe merge contract is defined entirely in terms of structural owners, match keys, and rendering behavior.
No comment surface is required by the ruleset.
This class is appropriate for formats or usage profiles where merge semantics are fully captured by structural ownership and value shaping alone.
layout_awareBlank-line gaps or similar non-token layout regions may carry ownership or preservation meaning.
This class is independent of comment support. A format MAY be layout-aware even if it has no comment syntax.
source_augmented_portable_writeComments or other non-structural annotations are discovered from source text or auxiliary tracking, while output is emitted through a portable write layer.
This class is appropriate when the parser does not expose a sufficiently editable native comment model, but the merge contract still requires preservation of non-structural content.
native_read_portable_writeComments or other non-structural annotations are read from parser-native structures or parser-provided attachment hints, while output is still emitted through a portable write layer.
This class is appropriate when native read fidelity exists, but implementation portability or merge-contract stability still depends on a ruleset-governed write layer.
native_mutationComments or other non-structural annotations are both read and emitted through native parser-owned structures.
This class is appropriate when the parser provides sufficiently complete mutation support for the merge contract to be satisfied without an intermediate portable write layer.
logical_ownerThe format contains merge-relevant artifacts whose preservation is determined by logical reference or semantic linkage rather than ordinary structural containment.
This class signals that pure structural presence is insufficient to describe full merge behavior.
In the standard vocabulary of this draft, declaration of one or more logical_owner directives is sufficient to establish that logical-owner semantics are part of the ruleset contract.
A bare capability logical_owner true declaration MAY advertise that such semantics exist, but it does not by itself declare any concrete logical-owner class or preservation policy.
This capability class indicates that logical-owner semantics are part of the ruleset contract. It does not by itself identify which logical-owner classes exist or what preservation policy each class requires.
A merge ruleset always describes the following core axes:
A merge ruleset MAY additionally declare optional axes when they are part of the merge contract:
A richer ruleset model MAY additionally describe:
A shared baseline owner selector pattern is:
all line-bound structural statements with stable start and end locations
This baseline is suitable for many structured line-oriented formats and is commonly the explicit owners declaration in such rulesets.
A ruleset SHOULD declare a more specific owner selector when the shared baseline is insufficient, including cases such as:
The following attachment strategies are defined:
layout_onlytracker_layout_mergeaugmenter_preferred_tracker_layoutnormalize_tracked_layout_mergeThese names define behavioral classes, not implementation language APIs.
A producer or consumer MAY derive a feature profile from the ruleset for inspection, diagnostics, conformance reporting, or other specification-facing reporting.
When a feature profile is exposed, it SHOULD summarize the declared behavior without inventing undeclared semantics.
In particular, omission of optional directives remains meaningful. A derived feature profile SHOULD distinguish between an undeclared surface and a declared surface whose value is known.
When backend information is exposed through a feature profile, the profile SHOULD distinguish family-level behavior from backend-specific capability or limitation reporting. A backend feature profile MUST NOT replace the ruleset as the normative declaration of merge behavior.
Some formats or implementations repeatedly encounter ambiguous states that are neither pure parser failure nor ordinary declarative merge behavior. Examples include:
A ruleset MAY declare one or more repair policies for such states so that consumers do not silently convert one behavior class into another.
A ruleset MAY declare one or more merge surfaces for embedded or nested content.
If delegation policy is declared for such content, it applies to a named declared merge surface rather than creating a surface implicitly.
If no delegate directive is declared for a given surface, the ruleset has not declared a distinct delegation policy for that surface. Consumers MUST NOT infer one implicitly from mere surface declaration alone.
Examples include:
The declaration of merge surfaces or delegation policies does not require a single universal runtime architecture. It only requires that a conforming consumer preserve the declared surface boundaries and delegation semantics at the observable behavior level.
Discovered surfaces MAY appear at multiple depths. Examples include:
@example surface discovered inside that documentation surface.When a consumer projects unresolved child-surface state into a parent result, it SHOULD preserve child identity rather than flattening the case into a parent-only ordinal.
A merge ruleset is a compact line-oriented declaration document.
Each non-empty non-comment line contains one directive.
Directives are space-separated tokens.
Comment lines begin with #.
The minimal grammar is defined in Appendix A.
A conforming ruleset MUST declare:
formatownersmatchreadattachThis draft intentionally keeps those directives mandatory even when a ruleset is primarily structural or layout-oriented. In such cases, the declared read and attach values define the normalized contract shape even if comment participation is absent or operationally minimal.
A conforming ruleset MAY additionally declare:
comment_stylerenderrender_strategybackendnode_roleatomicchild_groupcapabilitylogical_ownerrepairsurfacedelegateA ruleset consumer:
read and attach in Section 9).For the standard directives defined in this document, directive order is not itself semantically significant.
Repeated standard directives such as backend, node_role, atomic,
child_group, capability, logical_owner, repair, surface, and
delegate are cumulative declarations in this draft. Their relative order does
not define precedence unless some future extension explicitly introduces an
order-sensitive rule.
Within those repeatable directive families, the identifying key for each declaration is expected to be unique in this draft:
capability by capability name,backend by backend reference,node_role by node selector,atomic by node selector,child_group by parent selector and child-group name,logical_owner by logical-owner class,repair by named state class,surface by surface name,delegate by referenced surface name.Repeating the same identifying key with multiple standard declarations is malformed unless some future extension explicitly permits it.
By contrast, format, owners, match, read, attach, comment_style,
render, and render_strategy are singleton declarations in this draft.
Repeating any of those directives is malformed unless some future extension
explicitly permits repetition.
Namespaced extension directives or values MAY define their own order, repetition, or precedence rules. Such extension-specific rules are outside the standard directive model defined here unless explicitly incorporated by a future specification.
This section defines closed standard vocabularies for read and attach.
Other directives in this section may use standard names illustrated here, but unless a subsection explicitly declares a closed vocabulary, their values remain profile-specific or extension-permitted in this draft.
formatIdentifies the document family for human and machine-readable reference.
ownersDeclares the owner selector. The consumer MUST interpret this as a behavior declaration, not as executable code.
matchDeclares the match key strategy used to identify corresponding owners.
readDeclares the comment read/write capability class. Valid initial values are:
source_augmented_portable_writenative_read_portable_writenative_mutationThe read directive declares an observable behavior class, not a required internal architecture.
For example:
source_augmented_portable_write means comment or annotation fidelity originates from source scanning, auxiliary tracking, or equivalent non-native discovery while output remains governed by a portable write contract;native_read_portable_write means native parser fidelity contributes to annotation discovery while output remains governed by a portable write contract;native_mutation means native syntax-owned structures govern both read and write realization.How a consumer internally realizes these classes is out of scope provided the declared behavior is preserved.
For a structurally dominant or comment-free ruleset, the selected read class may have little or no operational effect on observable merge behavior. It remains part of the normalized ruleset contract surface defined by this compact syntax.
attachDeclares the attachment strategy. Valid initial values are:
layout_onlytracker_layout_mergeaugmenter_preferred_tracker_layoutnormalize_tracked_layout_mergeThese strategy names define observable attachment classes, not implementation APIs or object models.
At a minimum, a conforming consumer SHOULD preserve the following distinctions:
layout_only);tracker_layout_merge);augmenter_preferred_tracker_layout);normalize_tracked_layout_merge).The exact internal representation of tracked regions, augmenters, or attachment records is out of scope.
For a structurally dominant ruleset, the selected attachment strategy MAY be operationally trivial. It remains declaratively relevant because it states how non-structural ownership would be handled if such content participates in the merge contract.
comment_styleDeclares the surface comment family, such as:
hash_commentc_style_linehtml_commentThese names are illustrative in this draft unless a later profile or specification defines a closed comment-style vocabulary.
This directive MAY be omitted when comments are not part of the declared merge behavior.
renderDeclares the render family relevant to the owner surface.
The render family identifies the normalized output-shaping contract associated with the ruleset. It does not require a specific emitter API, serializer object model, or source-shaping pipeline.
Render-family names remain profile-specific in this draft unless a later profile or specification defines a closed vocabulary.
capabilityDeclares a named capability statement relevant to the ruleset contract.
One or more capability directives MAY be declared when the ruleset needs to express multiple semantic surfaces, support boundaries, limitations, or non-support cases.
Depending on the vocabulary in use, a capability declaration may:
Capability declarations complement the rest of the ruleset. They need not redundantly restate semantics that are already fully declared by other directives such as read, logical_owner, surface, or delegate.
If a standard capability declaration redundantly restates semantics already established by other standard directives, it MUST remain consistent with those directives. Contradictory redundant standard declarations are malformed in this draft.
Within the standard vocabulary of this draft, each capability name is declared at most once.
Examples include:
capability structural_only truecapability layout_aware truecapability inline_comments falsecapability quoted_hash_inline_literals not_applicablelogical_ownerDeclares preservation policy for a logical-owner class.
Where the capability class logical_owner signals that such semantics exist, one or more logical_owner directives MAY identify concrete logical-owner classes and their declared policies.
Declaring one or more logical_owner directives is itself sufficient to establish that logical_owner semantics are present. A redundant capability logical_owner true declaration is not required by this draft.
If a bare capability logical_owner true declaration is used, it advertises logical-owner semantics without replacing the need for logical_owner directives when concrete classes or policies must be declared.
Within the standard vocabulary of this draft, each logical-owner class is declared at most once.
Logical-owner class names and preservation-policy names are profile-specific in this draft unless a later profile or specification closes that vocabulary.
Examples include:
logical_owner link_definition preserve_if_referencedlogical_owner reference_target preserve_alwaysrepairDeclares handling for a named ambiguous, overlapping, or corruption-class state.
One or more repair directives MAY be declared when distinct state classes require distinct policies.
Within the standard vocabulary of this draft, each named state class is declared at most once.
Named state classes and repair-policy values are profile-specific in this draft unless a later profile or specification closes that vocabulary.
Initial values are intentionally policy-shaped rather than algorithm-shaped. Typical values include:
healwarnerrorskipA consumer MUST NOT silently apply undeclared repair behavior when the ruleset explicitly asks for a stricter policy.
When a declared repair policy or behavior profile allows recovery, the consumer SHOULD expose that activation through an observable diagnostic surface rather than making the widened acceptance path indistinguishable from baseline success.
When recovery is declared for a specific state class, consumers SHOULD preserve the original failure behavior for out-of-scope states rather than opportunistically reusing the same repair mechanism more broadly.
Consumers SHOULD also treat array resolution policy as a distinct merge surface from object-member resolution, even when an initial profile chooses a very simple baseline such as destination-wins replacement.
When multiple behavior-policy dimensions are exposed, consumers SHOULD identify them through an explicit policy surface plus named policy reference rather than embedding policy identity only in format-specific prose.
When a parse or merge result exposes active policy information, the consumer SHOULD report it as structured policy references rather than collapsing it into diagnostic text.
When an adapter or backend exposes policy support, the consumer SHOULD keep that capability metadata distinct from result-level active policy reporting.
When adapter capability metadata is exposed through a normalized feature profile, that profile SHOULD summarize capability surfaces without pretending to be runtime result state.
When a document-family package exposes a feature profile above a specific adapter, that higher-level profile SHOULD describe family behavior without requiring backend identity to be the primary reporting surface.
That family-level reporting pattern SHOULD be expressible through a shared core shape rather than remaining specific to one merge family.
As the shared fixture corpus expands, producers and consumers MAY rely on a small conformance manifest to identify stable portable fixture subsets without forcing each implementation to maintain its own divergent fixture index.
When backend identity is reported, consumers SHOULD prefer a normalized backend reference over implementation-local naming alone so future backend selection and conformance reporting do not collapse into package-specific strings.
When a shared fixture corpus is used across implementations, consumers MAY also rely on stable conformance roles in a manifest so representative fixture selection remains portable even as the corpus grows.
When a conformance manifest is exposed across implementations, consumers SHOULD prefer a normalized family-indexed manifest shape over family-specific top-level manifest fields so fixture discovery stays portable as more families are added.
Source-language families MAY participate in that same normalized manifest without introducing a source-language-specific manifest shape. When a source-language family supports multiple parser backends, a named suite SHOULD remain family-oriented while backend choice is supplied through a backend-aware family plan context.
Different source-language families MAY also select different parser backends in the same manifest-level planning or reporting pass so long as each family context remains explicit about its selected backend capability surface.
When a source-family manifest entry is meaningful only for a particular parser backend, that restriction SHOULD be expressed through ordinary case requirements rather than by introducing a backend-specific manifest shape or a backend-specific suite namespace.
The canonical shared manifest MAY also widen incrementally by admitting new
families through family_feature_profiles and the families map before those
families are promoted into the canonical suite set.
When case-level conformance reporting is exposed, consumers MAY also derive or report a normalized suite summary so aggregate status remains portable without replacing case-level evidence.
When capability-aware conformance selection is exposed, consumers SHOULD report selection explicitly rather than silently omitting unsupported cases. A skipped case remains observable conformance evidence when the skip is derived from declared dialect or policy support boundaries.
When reusable conformance runner helpers are exposed, consumers SHOULD preserve ordinary case-result reporting for skipped cases rather than introducing a separate hidden skip channel. Suite-level execution MAY be layered above such a case runner so long as ordered case results remain observable and compatible with normalized suite-summary derivation.
This draft does not define a standard unresolved directive or a standard persistence format for reviewable unresolved outcomes. Consumers MAY expose such runtime outcomes so long as they do not present them as additional declared ruleset directives unless a later profile or specification standardizes them.
When a consumer does expose a reviewable unresolved runtime outcome, it MAY report that operation as unresolved rather than completed even if a provisional emitted result is also available for inspection.
surfaceDeclares a named merge surface that may be selected or discovered within the host document.
One or more surface directives MAY be declared when the host format contains multiple merge-relevant embedded or nested regions.
Within the standard vocabulary of this draft, each surface name is declared at most once.
Surface names and selectors are profile-specific in this draft unless a later profile or specification closes that vocabulary.
Examples include:
surface fenced_code_block language_tagsurface doc_comment fixed_kinddelegateDeclares the delegation policy for a named merge surface.
One or more delegate directives MAY be declared when multiple declared merge surfaces require distinct delegation policies.
A delegate directive refers to a declared surface by name. It does not implicitly declare a merge surface on its own.
Absence of a delegate directive for a declared surface does not imply an undeclared default policy in this draft; it only means that no distinct delegation policy has been declared for that surface.
Delegation-policy names are profile-specific in this draft unless a later profile or specification closes that vocabulary.
Within the standard vocabulary of this draft, each declared surface has at most one delegation policy declaration.
Examples include:
delegate fenced_code_block by_languagedelegate doc_comment same_rulesetThis directive describes observable delegation intent. It does not require any specific implementation mechanism.
render_strategyDeclares the output-shaping strategy used for the rendered merge result.
Initial strategy names are profile-specific in this draft. Common strategy classes include:
source_fragment_reusenative_printercanonical_renderportable_write_layerfallback_conflict_renderThe render strategy does not guarantee byte-identical output. It identifies the declared route by which the implementation attempts to satisfy the render family and formatting-preservation contract.
backendDeclares a backend reference relevant to the ruleset, a profile, or a conformance case.
The backend directive is optional. A ruleset that omits it remains
backend-neutral. A consumer MUST NOT infer that an omitted backend directive
means all backends are equivalent.
Backend declaration values are profile-specific in this draft. A consumer that cannot satisfy an explicit backend requirement MUST reject or skip the affected case visibly rather than silently selecting a different backend.
Examples include:
backend go-parser supportedbackend go-dst supportedbackend tree-sitter supportednode_roleDeclares the merge role for a node selector or node class.
Node-role declarations are intended to make per-language classification rules portable without forcing every implementation to expose the same parser-native node names.
Examples include:
node_role import_declaration structuralnode_role line_comment commentnode_role semicolon separatornode_role parse_error erroratomicDeclares whether a selected node or owner is merged as an indivisible unit under the current ruleset.
Examples include:
atomic string_literal trueatomic function_body falseAtomic declarations MAY be used with node roles, owner selectors, or backend-limited conformance cases. A consumer MUST NOT descend into an atomic node for ordinary child merge unless an explicit delegated surface or future extension permits that behavior.
child_groupDeclares a named child group under a selected parent surface.
The final argument describes the ordering or merge-policy class for that group. Initial values are profile-specific, but common classes include:
orderedunorderedcommutativedestination_orderExamples include:
child_group source_file imports unorderedchild_group source_file declarations orderedchild_group object_literal properties commutativeChild-group declarations allow a ruleset to use richer tree semantics without requiring a single mandated intermediate tree algorithm.
The following ruleset is a normative example of a valid compact merge ruleset:
format toml
owners line_bound_statements
match signature
read native_read_portable_write
attach normalize_tracked_layout_merge
comment_style hash_comment
render toml_pairs_and_tables
A conforming ruleset consumer:
format, owners, match, read, and attach as required directives, and MUST correctly interpret the declared optional directives comment_style and render when present.read native_read_portable_write as a declaration that comment read fidelity originates from native parser support or parser-provided attachment hints while output is governed by a portable write contract.attach normalize_tracked_layout_merge as a declaration that tracked attachment data is merged with shared layout ownership and normalized where layout-owned leading regions need explicit surfacing.format dotenv
owners assignment_lines_plus_freeze_blocks
match env_key
read source_augmented_portable_write
attach tracker_layout_merge
comment_style hash_comment
render dotenv_assignments
capability template_only_comments false
format jsonc
owners line_bound_statements
match signature
read source_augmented_portable_write
attach augmenter_preferred_tracker_layout
comment_style c_style_line
render json_object_pairs
capability quoted_hash_inline_literals not_applicable
format markdown
owners link_definitions
match normalized_reference
read source_augmented_portable_write
attach tracker_layout_merge
comment_style html_comment
render markdown_link_definitions
logical_owner link_definition preserve_if_referenced
capability remove_template_missing_nodes false
capability inline_comments false
surface fenced_code_block language_tag
delegate fenced_code_block by_language
surface doc_comment fixed_kind
delegate doc_comment same_ruleset
repair comment_ownership_overlap warn
A conforming ruleset consumer:
delegate directive that refers to an undeclared surface unless an extension mechanism explicitly permits such indirection.surface.Early adoption is improved if the ecosystem develops:
The ruleset model is likely to stabilize faster if:
An adoption strategy that combines early conforming implementations with shared fixtures is therefore RECOMMENDED as a practical path toward broader interoperability evidence.
This document aims at semantic interoperability, not byte-identical output.
Two implementations can both conform while differing in:
However, interoperability improves when implementations consuming the same ruleset agree on:
Interoperability does not require shared internal representations for:
Those remain implementation detail so long as normalized ruleset meaning is preserved at the observable behavior level.
When unresolved review state is exchanged between tools or processes, raw local case identifiers alone are not sufficient for interoperability. Interoperability in that scenario depends on whether implementations agree about the semantic identity of a reviewable case and about what constitutes a compatible replay context.
Merge rulesets affect how configuration, source, or content documents are reconciled. An incorrect or malicious ruleset can:
Implementations SHOULD:
This document has no IANA actions.
Existing RFCs closest to this topic include:
Those documents standardize change transport, patch documents, or differencing formats. They do not standardize:
This document is therefore complementary to existing patch standards rather than competitive with them.
At present, the strongest common result is a shared vocabulary and a declarative ruleset structure, not a universally proven merge algorithm.
Informational status is appropriate because:
If this model demonstrates adoption across independent implementations and document families, a future BCP or Standards-Track effort MAY become appropriate.
Draft 02 preserves the compact ruleset model from Draft 01 while making the prior-art-driven implementation direction explicit.
Major changes include:
backend, node_role, atomic, child_group, and
render_strategy directives,The following ABNF describes the minimal compact ruleset syntax.
ruleset = *(blank-line / comment-line / directive-line)
blank-line = *WSP line-end
comment-line = *WSP "#" *not-line-end line-end
directive-line = *WSP directive *(1*WSP argument) *WSP line-end
directive = identifier
argument = identifier / boolean / token
identifier = ALPHA *(ALPHA / DIGIT / "_" / "-" / ".")
boolean = "true" / "false"
token = 1*(%x21 / %x24-7E)
not-line-end = %x00-09 / %x0B-0C / %x0E-7E / UTF8-non-ascii
line-end = LF / CRLF
This grammar is intentionally minimal. A future specification MAY define:
| Feature | Producer MUST | Consumer MUST | Notes |
|---|---|---|---|
| Parse required directives | Yes | Yes | format, owners, match, read, attach |
| Reject unknown required directives | N/A | Yes | Unknown required directive names are hard failures |
| Treat standard directive order as non-semantic | No | Yes | Producers MAY emit any order; repeated standard directives are cumulative unless a future extension declares otherwise |
| Reject malformed required directives | N/A | Yes | Hard failure |
| Reject malformed declared optional directives | N/A | Yes | Optional to declare, not optional to validate once declared |
| Reject repeated singleton standard directives | N/A | Yes | format, owners, match, read, attach, comment_style, render, and render_strategy are singleton declarations in this draft |
| Reject duplicate identifying keys within repeatable standard directives | N/A | Yes | Applies to repeated backend, node_role, atomic, child_group, capability, logical_owner, repair, surface, and delegate declarations using the same key |
| Reject contradictory redundant standard capability declarations | N/A | Yes | Redundant capability statements cannot contradict semantics already established by other standard directives |
| Reject unknown values for required standard directives with constrained vocabularies | N/A | Yes | In this draft, the closed required standard vocabularies are read and attach; no silent remapping |
| Reject unknown values for declared optional standard directives with constrained vocabularies unless extensions permit them | N/A | Yes | Applies where a later subsection or future specification defines a closed optional standard vocabulary |
| Do not silently reinterpret one declared strategy as another | N/A | Yes | Declared standard strategy values are not remapped to nearby alternatives |
Support comments beginning with # |
Yes | Yes | Ruleset-level comments, not merged document comments |
| Support namespaced extension directives or values | No | No | Optional |
| Preserve declarative meaning of owner selector | Yes | Yes | No executable-code dependency |
| Permit omission of optional directives when those surfaces are outside the declared contract | Yes | Yes | For example, comment_style or render may be absent when undeclared |
| Correctly interpret declared optional directives when present | No | Yes | Includes comment_style, render, capability, logical_owner, repair, surface, and delegate |
Reject delegate references to undeclared surfaces |
N/A | Yes | Delegation policy does not implicitly declare a merge surface |
| Do not infer undeclared delegation policy from a declared surface alone | N/A | Yes | Surface declaration and delegation declaration remain distinct |
| Surface unsupported capability declarations | N/A | Should | Diagnostic behavior |
| Honor declared repair-policy semantics | Yes | Yes | No silent remapping from error to healing |
| Surface visible repair-policy activation | N/A | Should | Warning/error/diagnostic behavior |
| Preserve declared merge-surface boundaries and delegation policies | Yes | Yes | Especially for embedded-language cases |
| Honor explicit backend requirements | Yes | Yes | No silent backend substitution |
| Honor node-role, atomic-node, and child-group declarations | Yes | Yes | Or surface unsupported-capability diagnostics |
| Report render strategy or source retention where relevant | No | Should | Especially for default merge-driver recommendation |
| Expose normalized feature profile meaning, if such a profile is exposed | N/A | Should | Derived reporting surface; preserve meaningful omission of undeclared optional directives |
| Guarantee byte-identical merged output | No | No | Out of scope |
| Guarantee semantic-equivalent declared behavior | Yes | Yes | Core intent |
The central claim of this document is that structured document merge is its own interoperability problem. It is not reducible to line diff, patch application, or plain tree replacement. The recurring portable concepts are:
Those concepts appear standardizable even where one universal merge algorithm does not.