build: schema definitions are named after the types they describe

[gennaroprota]

The generated RELAX NG and JSON schemas named nearly every definition after a symbol ID, as in S_21EdS1EVSJuD9X76CVhzhLTLg1fi, so neither told a reader what a definition describes, and a change in how Clang computes IDs rewrote both files. Each definition is now named after the type it describes.

While at it, the JSON schema is fixed to use the definition keyword instead of $defs, which was introduced by a later draft.

Changes

• Source: docs/mrdocs/extensions/schema.js names each definition after the type it describes, such as FunctionSymbol or RecordTranche. When two types share a name, each is qualified with as many enclosing scopes as it takes to tell them apart, joined with ., as in doc.Text; a name taken by one of the fixed definitions (Mrdocs, Tagfile, AnySymbol, ...) is qualified the same way. The ID remains the name of last resort, for types whose whole qualified names coincide. Separately, the JSON schema declares draft-07 but kept its definitions under $defs, a keyword that draft-07 does not define and that only the 2019-09 draft introduced; they are now under definitions, the draft-07 keyword. The schema stays on draft-07 rather than moving to a later draft, as the configuration schema declares draft-07 as well.
• Build: The two schemas under docs/modules/ROOT/attachments/schemas/generators/ are regenerated. No MrDocs type shares a name with another, so every definition gets its plain type name and no ID remains. The DOM reference partial is unchanged, as it never used these names.

Testing

The existing tests cover the change. xml-lint validates every golden XML fixture against the regenerated RELAX NG schema. schema-check regenerates the schemas and compares them with the committed ones, and CI compiles the JSON schema with ajv. The qualification rule is not exercised by MrDocs's own types, since none of them collide; it was checked on made-up types sharing a name, sharing a whole qualified name, and clashing with a fixed definition.

Documentation

The generators reference page, next to its links to the two schemas, now states how definitions are named.

Fixes #1297.

[github-actions]

🧾 Changes by Scope

Scope	Lines Δ%	Lines Δ	Lines +	Lines -	Files Δ	Files +	Files ~	Files ↔	Files -
📄 Docs	100%	518	291	227	4	-	4	-	-
Total	100%	518	291	227	4	-	4	-	-

Legend: Files + (added), Files ~ (modified), Files ↔ (renamed), Files - (removed)

🔝 Top Files

• docs/modules/ROOT/attachments/schemas/generators/mrdocs.schema.json (Docs): 210 lines Δ (+105 / -105)
• docs/modules/ROOT/attachments/schemas/generators/mrdocs.rng (Docs): 206 lines Δ (+103 / -103)
• docs/mrdocs/extensions/schema.js (Docs): 100 lines Δ (+82 / -18)

Generated by 🚫 dangerJS against 5e64df6

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 83.12%. Comparing base (adc6242) to head (5e64df6).

Additional details and impacted files

@@           Coverage Diff            @@
##           develop    #1321   +/-   ##
========================================
  Coverage    83.12%   83.12%           
========================================
  Files           35       35           
  Lines         3662     3662           
  Branches       844      844           
========================================
  Hits          3044     3044           
  Misses         410      410           
  Partials       208      208           

Flag	Coverage Δ
bootstrap	83.12% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[cppalliance-bot]

An automated preview of the documentation is available at https://1321.mrdocs.prtest2.cppalliance.org/index.html

If more commits are pushed to the pull request, the docs will rebuild at the same URL.

2026-09-24 10:10:09 UTC