[goloroden]

Closes #72

What changed

A document that failed schema validation was reported with the actual defect plus the consequences of the branch the validation failed on. A bounded context declaring a ubiquitousLanguage without language produced three findings, two of which named valid fields; a Given-When-Then rejection carrying the removed reason field produced four, of which only the last described the document. A reader who followed the first finding was sent in the wrong direction, and with the 0.15.0 migration those two shapes are exactly what upgrading users meet.

One defect now yields one finding. Never more, and never none.

Fewer findings: dropping the follow-on errors

unevaluatedProperties fallout. The core schema dispatches kinds through allOf with if/then and closes the document with unevaluatedProperties: false. A failed branch drops its annotations, so every field that branch would have evaluated counts as unevaluated and reads as an unknown field. An unknown field finding is now dropped when some failing branch below the same schema position declares that property, and kept otherwise. A genuine typo appears in no branch and survives: a bounded context missing language that also carries bogusField still reports both, and an Event whose data is misspelled as dat reports the missing data next to the unknown dat.

oneOf. The validator reports the causes of every alternative, so the findings of branches the document never intended stand next to the real one. The branch the document aims at is identified by how much of it the document already exhibits: one point per required property that is present, one more per property whose const it matches. The highest unique score wins and only that branch is reported. A tie reports every branch, because then the document genuinely identifies none, which is the accurate answer for something like then: {}.

Both decisions need the schema itself, not just the error. The library exposes no ErrorKind for unevaluatedProperties and no lookup of a subschema by pointer, so the decoded schema document is kept next to every compiled validator and addressed by the JSON pointer inside each error's SchemaURL.

More findings: breaking the silence

Two keywords fail without nested causes, and a translation that only walks causes turns such a failure into no diagnostic at all.

not is how the schema forbids a field depending on the value of a sibling: an Actor of type human has no backedBy. That document was reported with three unknown-field findings for valid fields before the filters above, and with nothing at all after them, so this is a regression the first commit would have introduced on its own. It now yields one finding naming the field and the condition, both read back out of the schema because the failure carries neither:

error: esdm/structure/constraint-violation
  at actor.esdm.yaml:8:1
  field "backedBy" is not allowed when "type" is "human"

A oneOf whose branches match more than once fails the same way, since there is no failing branch to point at. All 23 oneOf occurrences across the three schemas were checked pairwise: every pair is separated by a contradicting const or by a closed object, so no embedded schema can produce this today. It is covered because the failure mode is silence and a schema change could introduce it unnoticed.

error: esdm/structure/constraint-violation
  at document.esdm.yaml:12:3
  matches more than one of the forms allowed here; exactly one must apply

Beyond those two, a wrapper error that produced nothing now reports itself, whatever the reason the translation had nothing to say.

Both phrasings and the choice of constraint-violation over a new rule ID were signed off before implementing. The existing entry for that ID already covers them word for word: "a combination of fields the schema forbids."

Fewer findings, again

Two ways were left for one defect to draw more than one finding.

Alternatives failing on the same field reported it once each. An Event whose scope misspells aggregate fits neither alternative better, so both are reported, and both name the misspelled field. A diagnostic that repeats one already in the list is now dropped.

An alternative that is itself a set of alternatives states its requirements one level down, where the comparison against its siblings could not see them. It scored nothing, lost to any flat sibling, and left the comparison tied, which reports everything. A Process Manager whose reaction misspells event drew six findings that way. Affinity now reaches through such a branch and takes the score of the variant the instance comes closest to.

before: 6 findings, incl. "missing required field \"timer\"" and three unknown fields
after:  missing required field "event"
        unknown field "evnt"

Why it is safe

Filtering findings has one dangerous direction: silencing a defect outright. A mutation sweep guards it. It renames one field at a time across the kinds whose schemas combine branches and insists that a finding naming that field survives. Run over a wider corpus of 18 documents covering every such kind, all 435 mutations that make a document invalid still yield a finding that names the mutated field, none is silenced and none is repeated. The finding count over those 435 drops from 2647 to 803. Both filters were verified by sabotage: forcing either one to over-suppress fails the sweep.

The sweep did not catch the not case, because renaming a field never adds a forbidden one. That case has its own test, and the wrapper fallback now rules the failure mode out structurally.

Open for review

The Linter Rules entries for unknown-field and missing-required-field were checked, as the issue asked. Both still describe what the finding means, so they are unchanged. What changed is how many findings one defect produces, which belongs to neither entry, so one sentence in the introduction of the Pipeline Diagnostics section states it instead. That sentence is the only unprompted user-facing wording in this PR and is easy to drop.

🤖 Generated with Claude Code

https://claude.ai/code/session_011GYE7CQJ77q3Ne4QMgUFT1