Skip to content

Commit 58650e0

Browse files
JeroenDeDauwclaude
andauthored
Cut three restatements from ADR 26 (#1093)
Follows-up to #1091 Second text-review pass over the same ADR, for signal-to-noise: * Severity-in-responses was stated twice in the Decision section: as a fourth "blocking semantics" bullet (which is not about blocking) and again in "Wire format and domain model". Merged into the latter, which picks up the bullet's purpose clause; the bullet list is now purely about blocking. * "Schemas play no part in it" restated the "alone" in "decided by code and the wiki-level switch alone", and the next sentence draws the same contrast a third time. * The trailing "per Constraint" in the first Pro restated "which Constraints are strict". Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
1 parent 19831d5 commit 58650e0

1 file changed

Lines changed: 7 additions & 9 deletions

File tree

docs/adr/026-validation-severity-levels.md

Lines changed: 7 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -18,9 +18,8 @@ The current mechanism cannot serve both. Enforcement is a per-wiki boolean (`$wg
1818
is on, a write is rejected with a 422 only if it introduces violations that were not present on the prior revision,
1919
so pre-existing invalidity never locks a Subject. Every violation blocks except `schema-not-found`, which is
2020
hardcoded as non-blocking. Validation is thus already two-state in behavior, but which state a violation falls into
21-
is decided by code and the wiki-level switch alone; Schemas play no part in it. We want that decision in the hands of
22-
schema authors, per Constraint, and ADR 21 anticipated exactly this kind of "Schema-scope-or-below severity-level
23-
work".
21+
is decided by code and the wiki-level switch alone. We want that decision in the hands of schema authors, per
22+
Constraint, and ADR 21 anticipated exactly this kind of "Schema-scope-or-below severity-level work".
2423

2524
ADR 21 also carries forward a requirement first recorded in [ADR 12](012-backend-validation.md): invalid Subjects are
2625
a normal, supported state. Schema changes can invalidate persisted Subjects at any time, so the system keeps invalid
@@ -40,8 +39,6 @@ Blocking semantics:
4039
block. The newly-introduced-violations check from ADR 21 is unchanged, and severity is not part of violation
4140
identity in that check: changing a Constraint's severity does not make an existing violation count as new.
4241
* With enforcement off, no violation blocks, as today.
43-
* Validate and write responses always include severity, so UIs and API consumers can distinguish the tiers regardless
44-
of the enforcement setting.
4542

4643
The default severity is `warning`. The architecture treats invalid Subjects as a normal state (the ADR 21 requirement
4744
above), so surfacing a violation without blocking is the consistent default, and blocking is the exception a schema
@@ -98,15 +95,16 @@ because enforcement is off by default and an admin can lift it for the duration
9895
### Wire format and domain model
9996

10097
Every serialized violation gains an always-present `"severity": "error" | "warning"` field, in the dry-run validate
101-
endpoints' 200 body and in the enforcement 422 body alike. In the domain model, every violation carries its severity,
102-
stamped at validation time from the violated Constraint's configuration or the fixed classification above.
98+
endpoints' 200 body and in the enforcement 422 body alike, so UIs and API consumers can distinguish the tiers
99+
regardless of the enforcement setting. In the domain model, every violation carries its severity, stamped at
100+
validation time from the violated Constraint's configuration or the fixed classification above.
103101

104102
## Consequences
105103

106104
Pros:
107105

108-
* Schema authors control which constraints are strict and which are advisory, per Constraint. Messy imports can be
109-
persisted with warnings while essential fields still block.
106+
* Schema authors control which Constraints are strict and which are advisory. Messy imports can be persisted with
107+
warnings while essential fields still block.
110108
* API responses distinguish warnings from errors, and the frontend can style them accordingly (Codex `warning` vs
111109
`error` status).
112110
* The wire format change is additive, and existing Schema JSON stays valid via the scalar shorthand.

0 commit comments

Comments
 (0)