feat: generate a docs page per JSON Schema#10
Open
MentorFilou wants to merge 1 commit into
Open
Conversation
Renders /docs/schemas/<name>-<format>/ from the served schema files, so the human-readable reference and the machine-readable artifact cannot drift - they are the same bytes from the same release checkout. The renderer fails loudly: an unrecognized keyword aborts the build naming its JSON pointer rather than rendering a page that silently drops a constraint. Conditionals are resolved rather than dropped, so a top-level allOf/if/then annotates fields as conditionally required instead of misreporting them as optional. A version picker on the title line shows one version at a time, driven by a JS-only control that is styled away when scripting is off. Formats other than JSON are still served, just without a page, and the build says so rather than letting them vanish. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
MentorFilou
added a commit
that referenced
this pull request
Jul 20, 2026
Every version entry carried the parsed document alongside its bytes, and nothing in this PR read it - the site serves bytes and never a re-serialisation. The parse itself stays: it is what catches a release shipping a schema that will not parse, and that check is the reason the URL can be treated as a contract. Only the result is discarded, so there is no second representation of a schema able to drift from the one being served. Note for #10, which is stacked on this branch: src/schema-doc.mjs reads versions[].json to render its page. It should parse the bytes where it needs the document, keeping the parsed form local to the consumer that wants it. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Generates a human-readable reference page per schema from the files #9 serves, so the page and the machine-readable artifact cannot disagree — same bytes, same release checkout.
Based on
feat/serve-schemas(#9), so the diff here is the generation only. GitHub retargets this tomainautomatically once #9 merges. No rush on this one — #9 is the part worth merging quickly.What lands
/docs/schemas/report-json/Plus a "Schemas" group in the docs sidebar and a version picker on the title line.
Decisions worth reviewing
The renderer fails loudly. An unrecognized keyword aborts the build naming its JSON pointer (
#/$defs/item/properties/tags/maxItems) rather than rendering a page that silently drops a constraint. ExtendingKNOWN_KEYWORDSin src/schema-doc.mjs means deciding how the new constraint displays — it should not be widened just to get a build green.Conditionals are resolved, not dropped. The top-level
allOfis walked alongside the base schema by instance location, sothen.required: ["forwards"]annotates the top-level table andthen.properties.items.items.required: ["wantedBy"]resolves through the element$refand annotates theitemdefinition. Both render asRequired when mode is "rich"instead of a misleadingOptional.Page URL is format-qualified (
report-json, notreport), so a futurev1.xmlgets its own page instead of fighting over one URL.A format we cannot render is still served. Only JSON gets a page; anything else is published and warns, rather than vanishing silently.
The version picker is JS-only.
layout.mjsmarks the document scripted before first paint, so the control is styled away without scripting and the version filtering never flashes in.Verified locally
dist/built from this branch is byte-identical to the build from the original combined branch (diff -r), so the split changed no output/docs/schemas/report-json/matches the schema'srequiredarray, withforwardscorrectly shown as rich-mode-conditional#anchorresolves to a heading that exists$defs/ in a property / in athen-branch each report their pointer; unresolvable and remote$reffail;allOfwithoutif/thenfails;v10sorts abovev9schemas/upstream: warns, skips, builds 13 pages as beforeSequencing
Supersedes the documentation half of #8.
schemas/is not in a flashtrace release yet, so this stays dormant until a release ships it.🤖 Generated with Claude Code