Section structure
Which child sections a scope allows, in what order, and how many times: strict, ordered, occurs, requiredWhen, exactlyOne.
First officer: Bridge, engineering, medbay. In that order, and nothing bolted on.
Quick reference
| Written as | Fails with | Applies to |
|---|---|---|
strict | unexpected-section error | document, section |
ordered | out-of-order error | document, section |
freeText | — | document, section |
occurs=<range> | too-few-repeats errortoo-many-occurrences error | section |
exhaustive | unmatched-instance-heading error | section (a masked occurrence selector) |
requiredWhen. | missing-section errormissing-conditional-section error | section |
forbiddenWhen. | forbidden-section-present error | section |
exactlyOne=<group-id> | exactly-one-group-unmet error | section |
Examples
strict
Closure: every child section must be one the contract declares here. Order is separate: add ordered for exactly the declared sections, in the declared order.
Only the declared sections passes
<!-- mdv: document strict -->
<!-- mdv: section required -->
## Summary
<!-- mdv: section required -->
## Changes## Summary
Docking rework shipped.
## Changes
Replaced the guidance patch.✓ passes
A section the contract does not declare is flagged
<!-- mdv: document strict -->
<!-- mdv: section required -->
## Summary
<!-- mdv: section required -->
## Changes## Summary
Docking rework shipped.
## Changes
Replaced the guidance patch.
## Gossip
The rover is jealous of the droid.✗ unexpected-section error · line 9
ordered
The declared child sections must appear in the declared relative order.
Sections in the declared order pass
<!-- mdv: document ordered -->
<!-- mdv: section required -->
## Summary
<!-- mdv: section required -->
## Changes## Summary
Docking rework shipped.
## Changes
Replaced the guidance patch.✓ passes
Sections out of order are flagged
<!-- mdv: document ordered -->
<!-- mdv: section required -->
## Summary
<!-- mdv: section required -->
## Changes## Changes
Replaced the guidance patch.
## Summary
Docking rework shipped.✗ out-of-order error · line 1
freeText
Opt this scope out of strict — arbitrary extra child sections are allowed.
Extra sections are allowed under freeText
<!-- mdv: document strict freeText -->
<!-- mdv: section required -->
## Summary## Summary
Docking rework shipped.
## Crew Banter
Free-form sections the contract does not list.✓ passes
occurs
This child section's cardinality (SPEC §3), in the one range grammar: 0., 1., N (exact), N., or .. min AND max are enforced; with a sibling heading. the matching headings select the instances, without one the exemplar heading is the literal selector.
Two occurrences of the section pass
<!-- mdv: section required occurs=2 -->
## Shift Log## Shift Log
Night shift: all quiet.
## Shift Log
Day shift: relay retuned.✓ passes
Too few occurrences are flagged
<!-- mdv: section required occurs=2 -->
## Shift Log## Shift Log
Night shift: all quiet.✗ too-few-repeats error · line 1
exhaustive
On a masked occurrence set: every real sibling heading at the selector's own declared level must match its mask or a declared literal sibling — anything else is an unmatched-instance-heading error. Independent of the parent's strict/freeText.
A sibling heading that fits no mask is flagged
<!-- mdv: section required occurs=1.. exhaustive heading.mask="Sol <num>" -->
## Sol 12## Sol 12
Rover drilled a core sample.
## Sol 13
Dust storm, rover parked.
## Random thoughts
Not a sol entry at all.✗ unmatched-instance-heading error · line 9
requiredWhen
This child section is required only when a condition holds: a frontmatter key equals a value (requiredWhen.), or a matching checkbox is ticked (requiredWhen.).
A section is not required while its box is unticked
<!-- mdv: section required -->
## Checklist
<!-- mdv: list -->
- [ ] Breaking change
<!-- mdv: section requiredWhen.checked="Breaking change" -->
## Migration notes## Checklist
- [ ] Breaking change✓ passes
A ticked box makes the section required
<!-- mdv: section required -->
## Checklist
<!-- mdv: list -->
- [ ] Breaking change
<!-- mdv: section requiredWhen.checked="Breaking change" -->
## Migration notes## Checklist
- [x] Breaking change✗ missing-conditional-section error · line 1
forbiddenWhen
The symmetric negative of requiredWhen: this child section must be ABSENT whenever frontmatter <key> equals <value>. Equality-only, front-matter only.
A section forbidden by front matter is flagged
<!-- mdv: section required -->
## Summary
<!-- mdv: section forbiddenWhen.front.status=accepted -->
## Open questions---
status: accepted
---
## Summary
Approved for launch.
## Open questions
Which relay do we retire first?✗ forbidden-section-present error · line 9
exactlyOne
This LITERAL child belongs to a sibling XOR group: the parent requires exactly one member sharing the same group id to be present, and emits one group-level diagnostic naming the group and its present members on zero or 2+. A member's own requiredWhen/forbiddenWhen evaluates first — only members currently permitted count toward the group. Groups are literal child sections only.
Two members of the group are flagged
<!-- mdv: section exactlyOne=design -->
## Sketch
<!-- mdv: section exactlyOne=design -->
## Prototype## Sketch
Pencil layout of the dock.
## Prototype
Cardboard model of the dock.✗ exactly-one-group-unmet error · line 5
Exactly one member of the group passes
<!-- mdv: section exactlyOne=design -->
## Sketch
<!-- mdv: section exactlyOne=design -->
## Prototype## Sketch
Pencil layout of the dock.✓ passes
See also: Strictness