Question: should spec §7.8 document fmt.sort_frontmatter_keys, a deliberately inert config field?

[dean0x]

This is a question, not a defect. Nothing here is broken; the answer is an editorial call about what the normative spec is for.

The situation

spec.md §7.8 mds.json Project Config (spec.md:1238-1261) documents the accepted config surface with a field table at spec.md:1256-1259. That table has exactly two rows:

Field
build.output_dir	documented
lint.rules	documented

There is no fmt section anywhere in §7.8.

But mds.json does accept one. crates/mds-cli/src/build.rs:105-106 declares:

#[serde(default = "default_sort_frontmatter_keys")]
pub(crate) sort_frontmatter_keys: bool,

and the rustdoc immediately above it (build.rs:92-96) states that sort_frontmatter_keys "is not wired into any formatting behavior yet" and "exists now purely so {"fmt": {"sort_frontmatter_keys": false}} parses".

It is deliberately inert, and that is already documented for users — README.md:209-211:

Reads a fmt section from mds.json ({"fmt": {"sort_frontmatter_keys": true}}) for forward compatibility — the field doesn't drive any formatting behavior yet; frontmatter key sorting is deferred to a future version.

It is also strictly validated despite being inert: supplying a wrong type is a hard config-load failure, covered by tests at crates/mds-cli/src/build.rs:1902-1916 ("not-a-bool" must fail config loading) and :1927-1935 (false must deserialize correctly).

So this is a real, type-checked part of the accepted mds.json schema that the normative spec does not mention.

The question

Should spec.md §7.8 document a config field that has no behaviour?

Arguments for documenting it:

• It is part of the accepted schema. A field that parses and type-validates but is absent from the spec is a surprise.
• An independent implementer writing an mds.json parser from the spec would reject {"fmt": {"sort_frontmatter_keys": true}} as unknown — yet this implementation accepts it. That is a genuine conformance divergence, not a cosmetic one.
• Forward compatibility is the field's entire purpose, and forward compatibility works better when it is specified.

Arguments against:

• The spec describes behaviour, and this field has none. Documenting it invites users to set it and expect an effect.
• Specifying it now may over-constrain the eventual design of frontmatter key sorting.
• A "reserved / accepted but inert" note may belong in a compatibility appendix rather than the main field table.

A middle option: document it in §7.8 explicitly flagged as reserved, currently inert, mirroring the README wording, so the schema is complete without implying behaviour.

Why deferred

Found during design work and deliberately scoped out of the current change. It is an editorial decision about spec philosophy that wants an owner ruling, not a code change.