Unique Items Validation in JSON Schema Arrays

Enforcing Unique Array Items

The uniqueItems keyword ensures that no two elements in an array are equal. When set to true, the validator rejects arrays containing duplicate values.

Basic Syntax

{
  "type": "array",
  "items": { "type": "string" },
  "uniqueItems": true
}

This accepts ["a", "b", "c"] but rejects ["a", "b", "a"] because "a" appears twice.

How the Example Schema Works

The schema demonstrates uniqueItems with three different element types:

1. tags — an array of unique strings. Tags like ["javascript", "typescript", "react", "nextjs"] are all distinct, so validation passes. Submitting ["react", "react"] would fail. This prevents users from adding the same tag twice.

2. permissions — an array of unique enum values from a fixed set. Each permission can appear at most once. ["read", "write"] is valid, but ["read", "read"] is not. This models a set of flags.

3. matrix — an array of unique arrays. Each inner array represents a row. The comparison uses deep equality: [1, 2] and [1, 2] are considered duplicates, but [1, 2] and [2, 1] are not (different order means different values).

Deep Equality Rules

JSON Schema uses deep structural equality to detect duplicates:

Value A	Value B	Equal?
"hello"	"hello"	Yes
1	1.0	Yes (same JSON number)
[1, 2]	[1, 2]	Yes
[1, 2]	[2, 1]	No
{"a": 1}	{"a": 1}	Yes
{"a": 1, "b": 2}	{"b": 2, "a": 1}	Yes (key order irrelevant)
null	null	Yes
true	1	No (different types)

Note that JSON objects are compared regardless of key order — {"a": 1, "b": 2} and {"b": 2, "a": 1} are considered equal.

Performance Implications

Checking uniqueness requires comparing every pair of elements, which is O(n^2) for naive implementations. For large arrays, this can be slow. Some validators optimize this with hashing, but if your arrays can grow very large (10,000+ elements), consider whether uniqueItems is worth the validation cost or whether you should enforce uniqueness at the application level.

Alternative: Using enum for Fixed Sets

If the set of allowed values is small and fixed, you can model it with enum on each item and uniqueItems: true. This effectively creates a "set of flags" pattern, which is cleaner than using an object with boolean values.