Use counterexamples without overstating the checker
What This Concept Is
A compatibility witness is one payload accepted under one contract and rejected under another. It makes a mismatch reproducible. Absence of a witness is meaningful only within the checker's model and its input assumptions.
Why It Matters Here
Real OpenAPI and protocol schemas include nesting, unions, formats and behavioral promises. A small bounded checker makes inclusion reasoning visible without pretending to implement every schema feature. It also distinguishes permitted output from output observed in a small test run.
Concrete Example
The lab represents each field by a required flag and one to three permitted strings. Both schemas reject unknown fields. Enumerate the union of field names and their declared values, including absence. A value outside both declarations cannot be accepted by either side and therefore cannot witness a difference. With at most three fields this search is bounded and understandable.
For each payload test old acceptance and new acceptance. Old-only acceptance supplies a request witness; new-only acceptance supplies a response witness. Sort fields and values and visit absence first to make the first witness deterministic. This is a reproducibility choice, not a claim that the witness is the best explanation for every reader.
Common Confusion / Misconception
A response schema may permit a value that the current implementation never emits. Conservatively reporting it exposes a possible contract break; distinguishing it from an actual observed break requires implementation evidence. Conversely, unchanged schemas can hide a change from cents to dollars, different sorting, changed authorization or a new default.
How To Use It
Implement the lab independently, retain hand predictions, then compare with the reference. Test an empty schema, an absent field, an empty string value, an unknown field and invalid schema metadata. When adapting the idea to a real API, use its actual schema dialect and consumer behavior, and keep semantic tests separate from syntax checks.
Check Yourself
Why can the enumeration omit undeclared string values? Why must absence differ from an empty string? What guarantee does a passing schema comparison make about monetary units? Why is observed absence of an enum value weaker than a contractual prohibition?
Mini Drill or Application
Create three independently designed schema pairs. For each predict both witness directions. Add a semantic change with no schema difference and show that the checker passes while a consumer behavior test fails. Document the boundary of the tool rather than “fixing” the test by suppressing that example.
Read This Only If Stuck
API Design Patterns — predictable APIs and evolution. Read the archive README for exact input restrictions before treating it as a general schema checker.