2026-09-28 · 6 min read · Rahul Chitturi
- json-schema
- validation
- arrays
JSON Schema unevaluatedItems constrains array locations that were not successfully evaluated by other applicable keywords. It is useful when a reusable tuple schema is extended through composition, but it depends on annotations produced during validation rather than only the array's length.
Surprising results often come from mixing dialects, confusing prefixItems with older tuple syntax, or assuming a failed anyOf branch evaluated its items.
Pin the dialect and map each index
Record the declared schema dialect, validator version, complete composed schema, instance, and result. For every array index, list the keyword and successful branch that evaluated it. Do not debug an extracted subschema if the production result depends on annotations from its parent.
- Confirm the validator implements unevaluatedItems.
- Distinguish prefixItems from the schema-valued items keyword.
- Count indexes from zero consistently.
- Preserve references and composition during reproduction.
Follow only successful evaluations
Annotations from successful allOf, anyOf, oneOf, conditional, and reference evaluations can contribute to the evaluated set. A branch that inspects an item but fails does not grant that item a permanent exemption from unevaluatedItems.
Reduce the schema one applicator at a time, but keep a final fixture against the complete schema. Validator error paths help locate the failure; they do not always expose the full annotation flow.
Build an index-boundary matrix
Use Flashman's JSON formatter for schemas and instances, diff for validator outputs, YAML/JSON converter for configuration copies, and regex tester when item strings use patterns.
Test empty arrays, exact tuple length, one extra item, several extras, failed branches, several successful branches, contains matches, nested arrays, references, draft changes, and every validator used in production.