2026-09-29 · 6 min read · Rahul Chitturi
- json-schema
- validation
- arrays
JSON Schema uniqueItems rejects an array when two items are equal under the dialect's deep-equality rules. It does not mean the values are unique by one business field, and it does not compare JSON text byte for byte.
Failures often appear after a client reorders object keys, sends 1.0 where another item is 1, or repeats a nested object that looks different only because of formatting.
Record the dialect and the raw instance
Save the schema dialect, validator name and version, the complete array, and the error path. Pretty-printing can hide whether two objects differ by key order, numeric notation, or an extra property.
- Keep the original payload, not only a reformatted copy.
- Note whether uniqueItems is inherited through composition.
- Count indexes from zero when reading the error path.
- Confirm the keyword is actually implemented by that validator.
Compare values the way the schema does
Objects compare as unordered maps of properties, so {a:1,b:2} and {b:2,a:1} are duplicates. Arrays stay ordered. JSON numbers that represent the same value are equal even when their text differs. Strings and booleans compare exactly.
uniqueItems does not project a single property. Two user objects with the same id and different names are not duplicates, and two objects with different ids can still collide if every property matches.
Separate schema equality from a business key
Use Flashman's JSON formatter to inspect items, diff to compare a suspected pair, the YAML/JSON converter when the schema lives in configuration, and the regex tester only for string fields inside those items.
If the contract needs uniqueness of one identifier, model that identifier explicitly and test it. uniqueItems is the wrong tool for database-style distinct keys, and it will not catch duplicates that differ by an ignored field.