Intent
A root document declares the values it needs as one complete draft-07 object
schema — the same declaration shape an imported component uses. xmd run
turns that schema's top-level properties into command-line flags and
environment variables, resolves them by precedence (individual option →
aggregate option → individual env var → aggregate env var → schema default),
validates the combined object against the root schema, and only then runs the
document body.
The declaration lives in frontmatter and the resolved values reach the document
the same way an imported component's do — explicit interpolation, root eval
bindings, bare binding interpolation.
Prior art: the parked draft
A draft of this design exists on the branch
wip/root-document-inputs
(commit 9d36541), which adds specs/root-document-inputs-spec.md and rewrites
the declaration sections of specs/executable-mdx-spec.md.
Do not merge or cherry-pick it. It predates #317 and #319, and its
specs/executable-mdx-spec.md hunks would revert both. The branch is a record
of the intent; the intent gets re-derived against current main and applied as
a fresh diff.
First task — blocking all others: a terminology decision
The parked draft uses three names for one concept:
inputs: in frontmatter{props.name} in the body--props-name / XMD_PROPS_NAME on the CLI
Per the Terminology registry's rules in architecture.md — only use terms
defined there or already in the spec and code, and ask before adding one —
inputs replacing props is a vocabulary decision that has to be settled
before any of this is specced or built. Questions for @taras:
- Does
inputs go everywhere — inputs: in frontmatter, {inputs.name}
in the body, --input-name, XMD_INPUT_NAME?
- Does
props survive as a distinct term for component invocation
attributes (what a caller passes at the call site), with inputs reserved
for the declaration?
- What are the resulting registry entries in
architecture.md?
Nothing else here should move until that is answered.
Notes
Intent
A root document declares the values it needs as one complete draft-07 object
schema — the same declaration shape an imported component uses.
xmd runturns that schema's top-level properties into command-line flags and
environment variables, resolves them by precedence (individual option →
aggregate option → individual env var → aggregate env var → schema default),
validates the combined object against the root schema, and only then runs the
document body.
The declaration lives in frontmatter and the resolved values reach the document
the same way an imported component's do — explicit interpolation, root eval
bindings, bare binding interpolation.
Prior art: the parked draft
A draft of this design exists on the branch
wip/root-document-inputs(commit
9d36541), which addsspecs/root-document-inputs-spec.mdand rewritesthe declaration sections of
specs/executable-mdx-spec.md.Do not merge or cherry-pick it. It predates #317 and #319, and its
specs/executable-mdx-spec.mdhunks would revert both. The branch is a recordof the intent; the intent gets re-derived against current main and applied as
a fresh diff.
First task — blocking all others: a terminology decision
The parked draft uses three names for one concept:
inputs:in frontmatter{props.name}in the body--props-name/XMD_PROPS_NAMEon the CLIPer the Terminology registry's rules in
architecture.md— only use termsdefined there or already in the spec and code, and ask before adding one —
inputsreplacingpropsis a vocabulary decision that has to be settledbefore any of this is specced or built. Questions for @taras:
inputsgo everywhere —inputs:in frontmatter,{inputs.name}in the body,
--input-name,XMD_INPUT_NAME?propssurvive as a distinct term for component invocationattributes (what a caller passes at the call site), with
inputsreservedfor the declaration?
architecture.md?Nothing else here should move until that is answered.
Notes