Rewrite validation-codes.md at the API-consumer altitude

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>

Author: JeroenDeDauw

docs/api/validation-codes.md

@@ -4,23 +4,17 @@ order: 4
 ---
 # Validation Codes
 
-Constraint violations returned by NeoWiki's backend validation API use stable `code` strings.
-This document is the authoritative reference for NeoWiki's PHP backend validation.
+Constraint violations returned by NeoWiki's validation API use stable `code` strings. This document is
+the reference for those codes.
 
 Violations are returned by:
 
 - `POST /neowiki/v0/subject/validate` — dry-run validation of a proposed create-shape body.
 - `POST /neowiki/v0/subject/{subjectId}/validate` — dry-run validation of a proposed update-shape
   body against an existing Subject's Schema.
 - `POST /neowiki/v0/subject` and `PUT /neowiki/v0/subject/{subjectId}` — the write endpoints include
-  the resulting `violations` array in their `201`/`200` success body. By default
-  (`$wgNeoWikiEnforceValidation = false`) the write always persists. When an admin enables
-  enforcement (`$wgNeoWikiEnforceValidation = true`), a write that introduces *new* blocking
-  violations is rejected with `422 Unprocessable Entity` and an `{ status, message, violations }`
-  body; `violations` carries the full proposed list, not just the newly-introduced subset.
-  Pre-existing violations (already present on the stored Subject under the current Schema) and
-  non-blocking codes such as [`schema-not-found`](#schema-not-found) never block, so editing an
-  already-invalid Subject stays possible. See [ADR 21](../adr/021-add-backend-validation.md).
+  the resulting `violations` array in their `201`/`200` success body. Whether a write with violations
+  is rejected is covered under [Blocking and enforcement](#blocking-and-enforcement).
 
 The `/validate` endpoints return `200 OK` with a `{violations: [...]}` body whenever the request is
 well-formed; violations in the body do not change the HTTP status. `400` is reserved for malformed
@@ -42,218 +36,151 @@ Each violation in the response has this shape:
 - `propertyName` is the property name as a string, or `null` for Subject-level violations.
 - `code` is one of the stable strings documented below.
 - `args` is always present; `[]` when there is nothing to interpolate.
-- `valuePartIndex` is the zero-based index into the offending Value's parts. The key is **omitted
-  from the JSON** when not applicable (Subject-level violations or property-level violations that
-  do not point at a single part).
+- `valuePartIndex` is the zero-based index of the offending part of a multi-part value. Only the
+  codes that document it set it; the key is omitted from the JSON otherwise.
+
+## Blocking and enforcement
+
+Three codes are non-blocking warnings: [`unregistered-type`](#unregistered-type),
+[`schema-not-found`](#schema-not-found), and [`relation-target-not-found`](#relation-target-not-found).
+They are marked "Non-blocking" below and never cause a write to be rejected. Every other code blocks.
+
+Blocking matters only when an admin enables enforcement (`$wgNeoWikiEnforceValidation`; off by
+default, so every write persists). Under enforcement, a write that introduces *new* blocking
+violations is rejected with `422 Unprocessable Entity` and an `{ status, message, violations }` body,
+where `violations` carries the full proposed list, not just the newly-introduced ones. Violations
+already present on the stored Subject never block, so an already-invalid Subject stays editable. See
+[ADR 21](../adr/021-add-backend-validation.md) and
+[ADR 26](../adr/026-validation-severity-levels.md).
 
 ## Code reference
 
 ### `required`
 
-Emitted by `SubjectValidator` (when a required property has no Statement on the Subject) and
-by every built-in PropertyType plus `ColorType` (RedHerb) (when a Statement is present but its
-Value is content-empty).
+A property declared `required: true` has no usable value. Fires when the Subject body has no
+Statement for the property, and when a Statement is present but its value is empty for its type:
+only whitespace (`text`, `date`, `dateTime`), no parts (`url`, `select`), no targets (`relation`),
+or no value at all (`number`, `boolean`).
+
 `args`: `[]`.
-`valuePartIndex`: never set.
-`propertyName`: attached by `SubjectValidator` (either directly when the schema-iteration loop
-emits, or via `withPropertyName()` from the per-type loop).
-
-Fires in two cases for any property declared `required: true`:
-
-1. **No Statement at all** — the Subject body did not include the property. `SubjectValidator`
-   iterates the Schema's properties after the per-statement loop and emits `required` for any
-   required property without a corresponding Statement. This also covers the case where the
-   client sent the property with an empty Value (e.g. `value: []`), because
-   `StatementListBuilder` drops empty-Value Statements before the validator runs, leaving the
-   schema-iteration loop to surface it.
-2. **Statement present but Value is content-empty** — emitted by the PropertyType validator.
-   What counts as "content-empty" depends on the type:
-   - `TextType` — no non-whitespace string in the `StringValue` parts.
-   - `UrlType`, `SelectType`, `ColorType` — `StringValue` has zero parts after deserialization.
-   - `NumberType` — the value is not a `NumberValue`.
-   - `RelationType` — the value is not a `RelationValue`, or has zero relations.
-   - `DateTimeType` — the value is not a `StringValue`, has zero parts, or its first part is
-     empty/whitespace.
 
 ### `label-required`
 
-Emitted by `SubjectValidator` only.
-`args`: `[]`.
-`valuePartIndex`: never set.
-`propertyName`: always `null` (Subject-level).
+The Subject's label is empty or whitespace-only. Subject-level: `propertyName` is `null`.
 
-The Subject's label is empty or whitespace-only.
+`args`: `[]`.
 
 ### `type-mismatch`
 
-Emitted by `SubjectValidator` only.
-`args`: `[writerType, currentType]` — the type recorded on the Statement when it was written
-and the type the Schema currently declares for the property.
-`valuePartIndex`: never set.
-`propertyName`: the affected property.
+The type recorded on the Statement when it was written (ADR 11) no longer matches the type the
+Schema currently declares for the property — for example, a Statement written while the property was
+a `url`, after the Schema changed the property to `number`. When this fires, it is the only
+violation reported for that property: per-type checks and `required` are suppressed.
 
-The Statement's writer's-schema type (the `propertyType` recorded when the Statement was
-written, per ADR 11) no longer matches the Schema's current type for that property. For example,
-a property was originally declared as `url` and a Statement was written carrying a `StringValue`;
-the Schema was later edited to make that property a `number`. The Statement is now invalid under
-the current Schema (ADR 12 names this case explicitly).
-
-`SubjectValidator` skips per-type validation when this fires — the per-type's `instanceof`
-PropertyDefinition guard would no-op against the wrong-typed definition anyway, and the more
-specific `type-mismatch` code is what a consumer needs to react.
-
-If a property is `required` AND its Statement has a type mismatch, only `type-mismatch` fires
-(the Statement is present, just under the wrong type). `required` would be redundant noise.
+`args`: `[writerType, currentType]`.
 
 ### `invalid-url`
 
-Emitted by `UrlType`.
-`args`: `[]`.
-`valuePartIndex`: index of the offending URL within the multi-part `StringValue`.
-`propertyName`: attached by `SubjectValidator`.
+On `url` properties. A non-empty value does not match the allowed URL pattern. The pattern accepts
+`http://` and `https://` schemes (or no scheme), domain-like hosts, IPv4 literals, `localhost`,
+port, path, query, and fragment. It rejects other schemes (`ftp://`, `file://`), spaces, and
+disallowed characters.
 
-A non-empty trimmed string in the `StringValue` does not match the allowed URL pattern. The
-pattern accepts `http://` and `https://` schemes (or no scheme), domain-like hosts, IPv4
-literals, `localhost`, port, path, query, and fragment. It rejects other schemes (`ftp://`,
-`file://`), spaces, and disallowed characters.
+`args`: `[]`. `valuePartIndex`: the offending part.
 
 ### `unique`
 
-Emitted by `TextType` and `UrlType`.
-`args`: `[]`.
-`valuePartIndex`: never set.
-`propertyName`: attached by `SubjectValidator`.
+On `text` and `url` properties with `uniqueItems` enabled: the value contains duplicate parts.
 
-The Property's `uniqueItems` constraint is enabled and the `StringValue` contains duplicate parts.
+`args`: `[]`.
 
-### `min-value`
+### `min-length` / `max-length`
 
-Emitted by `NumberType` and `DateTimeType`.
-`args`: `[minimum]`. For `NumberType` this is a `number`; for `DateTimeType` this is the ISO 8601
-string declared on the Property.
-`valuePartIndex`: never set.
+On `text` properties. A part's trimmed length is below `minLength` or above `maxLength`. Empty
+parts are not length-checked.
 
-The value is strictly below the Property's inclusive minimum.
+`args`: `[minLength]` / `[maxLength]`. `valuePartIndex`: the offending part.
 
-### `max-value`
+### `min-value` / `max-value`
 
-Emitted by `NumberType` and `DateTimeType`.
-`args`: `[maximum]`. Same shape as `min-value`.
-`valuePartIndex`: never set.
+On `number`, `date`, and `dateTime` properties. The value is below the property's inclusive
+`minimum` or above its inclusive `maximum`.
 
-The value is strictly above the Property's inclusive maximum.
+`args`: `[minimum]` / `[maximum]` — a number for `number` properties, the declared ISO 8601 string
+for `date` and `dateTime`.
 
 ### `invalid-option`
 
-Emitted by `SelectType` and RedHerb's `ColorType` (when `allowedColors` is non-empty).
-`args`: `[offendingPart]`.
-`valuePartIndex`: index of the offending part within the `StringValue`.
+On `select` properties. A part is not in the property's `options` allow-list.
 
-A part is not in the Property's allow-list (`options` for SelectType, `allowedColors` for
-ColorType).
+`args`: `[offendingPart]`. `valuePartIndex`: the offending part.
 
 ### `single-value-only`
 
-Emitted by `SelectType` and `RelationType`.
-`args`: `[]`.
-`valuePartIndex`: never set (Subject-property-level, not part-level).
+On single-valued (`multiple: false`) `select` and `relation` properties: more than one part
+(`select`) or relation target (`relation`) was supplied.
 
-The Property's `multiple` flag is false and more than one value was supplied — more than one part for
-`SelectType`, or more than one relation target for `RelationType`.
+`args`: `[]`.
 
 ### `invalid-datetime`
 
-Emitted by `DateTimeType`.
+On `dateTime` properties. The value is not a strict ISO 8601 / `xsd:dateTime` string with an
+explicit timezone offset or `Z`. Includes calendar-overflow cases like `2025-02-30T00:00:00Z`,
+partial dates (`2025`, `2025-06`, `2025-06-15`), and missing offsets.
+
 `args`: `[]`.
-`valuePartIndex`: never set (DateTime is single-valued).
 
-The non-empty first part of the `StringValue` is not a strict ISO 8601 / xsd:dateTime string
-with an explicit timezone offset or `Z`. Includes calendar-overflow cases like
-`2025-02-30T00:00:00Z`, partial dates (`2025`, `2025-06`, `2025-06-15`), and missing offsets.
+### `invalid-date`
+
+On `date` properties. The value is not a strict ISO 8601 calendar date (`YYYY-MM-DD`). Time or
+timezone components and calendar overflows like `2025-02-30` are rejected.
 
-### `invalid-color`
+`args`: `[]`.
+
+### `unregistered-type`
 
-Emitted by RedHerb's `ColorType`.
-`args`: `[offendingPart]`.
-`valuePartIndex`: index of the offending part within the `StringValue`.
+Non-blocking. The property's type has no registered PropertyType — typically the extension providing
+the type is disabled. The value cannot be interpreted, so it is preserved verbatim and no other
+checks run for the property. A required property of an unregistered type reports this code instead
+of `required`, so the Subject stays saveable.
 
-A part does not match the 6-digit hex-color pattern (`/^#[0-9a-fA-F]{6}$/`).
+`args`: `[propertyType]`.
 
 ### `schema-not-found`
 
-Emitted by `ValidateSubjectUpdateApi` and by the Subject write endpoints
-(`POST /subject`, `PUT /subject/{id}`) via `ProposedSubjectValidator`.
-`args`: `[schemaName]`.
-`valuePartIndex`: never set.
-`propertyName`: always `null` (Subject-level).
+Non-blocking. The Subject's Schema cannot be loaded — usually deleted or renamed since the Subject
+was created, or the Subject was created or imported referencing a Schema that does not (yet) exist.
+The write proceeds and reports the violation; creating or renaming the Schema page resolves it.
+Subject-level: `propertyName` is `null`.
 
-The Subject's Schema cannot be loaded — usually because the Schema page was deleted or renamed
-since the Subject was created, or because a Subject is created/imported referencing a Schema that
-does not (yet) exist. On the write endpoints it is non-blocking: the write proceeds and the
-(unvalidatable) Subject stays editable per ADR 21, but the response reports `schema-not-found`
-rather than an empty (and misleading "valid") violation list. The caller can resolve it by
-creating or renaming the Schema page.
+Returned by the update dry-run and both write endpoints. The create dry-run
+(`POST /subject/validate`) instead returns `404`, because there the Schema is the addressed
+resource.
 
-Note the create dry-run endpoint (`POST /subject/validate`) instead returns `404`
-(`SchemaNotFoundException`) for a missing Schema, because there it is the addressed resource;
-the update dry-run (`POST /subject/{id}/validate`) and both write endpoints surface the violation.
-Reconciling that asymmetry is left to the enforcement tier (ADR 21).
+`args`: `[schemaName]`.
 
 ### `relation-target-schema-mismatch`
 
-Emitted by `SubjectValidator`.
-`args`: `[expectedSchema, actualSchema]` — the target Schema the relation Property declares
-(`targetSchema`), and the Schema the resolved target Subject actually uses.
-`valuePartIndex`: index of the offending relation target within the `RelationValue`.
-`propertyName`: the relation property.
+On `relation` properties. The relation targets a Subject that exists but whose own Schema is not the
+property's declared `targetSchema`. A target that cannot be resolved is reported as
+[`relation-target-not-found`](#relation-target-not-found) instead. The subject editor filters
+relation candidates by target Schema, so this normally only occurs on API writes such as imports.
 
-A relation targets a Subject that exists but whose own Schema is not the Property's declared
-`targetSchema`. The Schema compared is the target's own stored writer's-schema, read from its revision
-slot rather than from a graph node property. Reaching that slot still resolves the target ID through
-the subject-to-page index, which lives only in the graph projection, so this check only runs for
-targets the graph currently knows about. This is a blocking `error` (ADR 26): it is rejected at write
-time when `$wgNeoWikiEnforceValidation` is enabled. The subject editor's picker filters candidates by
-target Schema, so this is normally only reachable through the API — for example a bulk import.
+`args`: `[expectedSchema, actualSchema]`. `valuePartIndex`: the offending target.
 
 ### `relation-target-not-found`
 
-Emitted by `SubjectValidator`.
-`args`: `[targetId]` — the target Subject ID that did not resolve.
-`valuePartIndex`: index of the offending relation target within the `RelationValue`.
-`propertyName`: the relation property.
-
-A relation targets a Subject ID that does not resolve to any existing Subject. It is a non-blocking
-`warning` (ADR 26), joining [`schema-not-found`](#schema-not-found) and `unregistered-type` in the
-hardcoded non-blocking set, so it never rejects a write even under enforcement. This is deliberate:
-pointing at a not-yet-created Subject is wiki-native red-link behavior, and an import may legitimately
-mint the target later.
-
-Resolution goes through the subject-to-page index, which lives only in the graph projection, so a
-target that exists in revision slots but is missing from the graph is reported as not found. An
-import populates the slots without updating the projection
-([#1022](https://github.com/ProfessionalWiki/NeoWiki/issues/1022)), so imported targets warn until
-[the graph is rebuilt](../operations/maintenance.md#rebuilding-the-graph). Being non-blocking, this
-misreport never costs a write.
+Non-blocking. On `relation` properties. The relation targets a Subject ID that does not resolve to
+any existing Subject. Deliberately a warning: pointing at a not-yet-created Subject is wiki-native
+red-link behavior, and an import may legitimately mint the target later.
 
-## Known limitations (Foundation round)
+`args`: `[targetId]`. `valuePartIndex`: the offending target.
 
-The PHP `SubjectValidator` performs these Subject-level checks:
+## Out-of-schema Statements
 
-- **`required`** — PHP iterates the Schema's properties to catch absent-required cases.
-- **`type-mismatch`** — PHP compares the Statement's writer's-schema type against the Schema's
-  current type and surfaces drift per ADR 11 / ADR 12.
-- **[`relation-target-schema-mismatch`](#relation-target-schema-mismatch)** and
-  **[`relation-target-not-found`](#relation-target-not-found)** — documented above; both need a
-  Subject lookup, which `PropertyType::validate()` has no access to.
-
-### Deliberate behavior, not a gap
-
-- **Out-of-schema Statements are silently skipped.** A Statement whose property is not declared
-  on the current Schema is ignored — no violation. This is schema-drift tolerance: a property
-  may have been removed from the Schema while Subjects still carry old Statements. ADR 8 says
-  one Schema per Subject, not that every Statement on that Subject must reference an extant
-  Property. If surfacing these as violations becomes useful (e.g. for migration UIs), it can be
-  added as a separate code without changing the current behavior.
+A Statement whose property is not declared on the current Schema is ignored — no violation. This is
+schema-drift tolerance: a property may have been removed from the Schema while Subjects still carry
+old Statements.
 
 ## Adding a new validation code
 
@@ -268,5 +195,7 @@ violation code:
    convention as the codes above.
 4. If the violation points at a specific part of a multi-part Value, set `valuePartIndex` to
    that part's zero-based index.
-5. Document your new code in this file (or your extension's documentation if you want it to be
-   discoverable independently).
+5. Document your new code in your extension's documentation.
+
+RedHerb's `ColorType` (`tests/RedHerb/src/ColorType.php`) is a worked example, including its own
+`invalid-color` code.