Rewrite validation-codes.md at the API-consumer altitude#1106
Merged
Conversation
Follows-up to #1082 A full text pass over the validation-codes reference for its actual reader: an API consumer deciding what a code means, whether their write fails, and what to do next. Everything that derived or justified the contract instead of stating it is gone: - Emitter-class names and validator-loop narration (SubjectValidator, StatementListBuilder, ...). Entries now use schema type names (`text`, `dateTime`) instead of PHP class names. - The relation-target resolution anatomy (revision slots, subject-to-page index, graph staleness, #1022): read consistency is a system-wide property homed in operations/maintenance.md, not something to restate per validation code. - Design-rationale asides and roadmap notes ("would be redundant noise", the 404-asymmetry reconciliation note). - The "Known limitations" inventory of which class performs which check — it duplicated the entries. - RedHerb's `invalid-color` entry: extension codes belong to the extension's docs (step 5 of the plugin-author section now says exactly that); RedHerb stays as the worked-example pointer. Blocking semantics now live in one "Blocking and enforcement" section instead of an intro bullet plus per-entry restatements; only the three non-blocking codes carry a marker, and per-entry propertyName/valuePartIndex lines that restated defaults are gone. Completeness fixes found on the way: `min-length`, `max-length`, `invalid-date`, and `unregistered-type` are emitted but were undocumented (the last was even referenced by name), and `min-value`/`max-value` are also emitted by `date` properties, which the emitter list omitted. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Context about which surface typically produces the code, not part of the contract; resolved toward this pass's cut-by-default policy. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
JeroenDeDauw
added a commit
that referenced
this pull request
Jul 20, 2026
Follows-up to #1106 #1106 rewrote `docs/api/validation-codes.md` to its reader's altitude and cut everything that derived, justified, or narrated mechanism rather than stating the contract. This adds `docs/writing.md`, which codifies that standard so the next page holds to it by default. The page states, in under 45 lines: a rule block (fix the reader, their decision, and a length budget before writing; state contracts, don't narrate mechanism; one home per fact; no history of the text's own production; improving a page doesn't lengthen it), a genre table assigning each `docs/` area its reader and register, and a short list of banned phrasings. Placement: `docs/writing.md` at the docs root, no frontmatter. The site nav is curated, not built from every file (`planning/` is excluded per `docs/README.md`), and published leaves carry the `title`/`order` frontmatter this page omits, so it stays out of the product navigation. The docs-deploy workflow only triggers the site build; the nav lives in the website project. Genre mapping: there is no `concepts/` or `reference/` directory, so those genres map to the docs-root concept pages and to `authoring/` + `rdf/` + `examples/`. Every existing `docs/` subdirectory is covered by one row. Considered, omitted: a standalone row for `examples/` (folded into the reference genre); `title`/`order` frontmatter (would list it in the nav); a cross-link from `docs/README.md` (this change adds one file only); a fuller description of the deploy pipeline (out of the page's genre). No repo-root `CLAUDE.md`/`AGENTS.md` exists, so no AI-context pointer was added. > <sub>AI-authored — Claude Code, `Opus 4.8 (max)`; executed from a fixed skeleton and genre assignments specified by a Fable 5 session directed by @JeroenDeDauw; not yet human-reviewed; placement verified against the docs-site build config, links checked, docs-only change.</sub> 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
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.
Follows-up to #1082
A full text pass over the validation-codes reference for its actual reader: an API consumer deciding
what a code means, whether their write fails, and what to do next. Everything that derived or
justified the contract instead of stating it is gone:
Entries now use schema type names (
text,dateTime) instead of PHP class names.Imported revisions do not update the graph projection #1022): read consistency is a system-wide property homed in operations/maintenance.md, not
something to restate per validation code.
reconciliation note).
invalid-colorentry: extension codes belong to the extension's docs (step 5 of theplugin-author section now says exactly that); RedHerb stays as the worked-example pointer.
Blocking semantics now live in one "Blocking and enforcement" section instead of an intro bullet
plus per-entry restatements; only the three non-blocking codes carry a marker, and per-entry
propertyName/valuePartIndex lines that restated defaults are gone.
Completeness fixes found on the way:
min-length,max-length,invalid-date, andunregistered-typeare emitted but were undocumented (the last was even referenced by name), andmin-value/max-valueare also emitted bydateproperties, which the emitter list omitted.