uniqueItems : Boolean

uniqueItems

Boolean

If this keyword is set to the boolean value true, the instance validates successfully if all of its elements are unique.

Value	This keyword must be set to a boolean value
Kind	Assertion
Applies To	Array
Base Dialect	2020-12
Changed In	None
Introduced In	Draft 2
Vocabulary	Validation
Specification	https://json-schema.org/draft/2020-12/json-schema-validation.html#section-6.4.3
Metaschema	https://json-schema.org/draft/2020-12/meta/validation
Official Tests	draft2020-12/uniqueItems.json
Default	`false`
Annotation	None
Affected By	None
Affects	None
Also See	prefixItems (Vocabulary: Applicator) items (Vocabulary: Applicator) contains (Vocabulary: Applicator)

When set to true, the uniqueItems keyword restricts array instances to items that only occur once in the array. Note that empty arrays and arrays that consist of a single item satisfy uniqueness by definition.

Common Pitfall

Keep in mind that depending on the size and complexity of arrays, this keyword may introduce significant validation overhead. The paper JSON: data model, query languages and schema specification also noted how the presence of this keyword can negatively impact satisfiability analysis of schemas.

Digging Deeper

While the official vocabularies do not offer a way to ensure uniqueness of array items based a given key, the json-everything project defines a third-party Extended Validation of Arrays vocabulary that introduces a uniqueKeys keyword for this purpose. However, keep in mind that third-party vocabularies are often not widely supported by implementations.

Remember that JSON Schema is a constraint-driven language. Therefore, non-array instances successfully validate against this keyword. If needed, make use of the type keyword to constraint the accepted type accordingly.

Examples

A schema that constrains array instances to not contain duplicate items Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "uniqueItems": true
}

Valid An array value without duplicate items is valid Instance

[ 1, "hello", true, { "name": "John" } ]

Invalid An array value with duplicate elements is invalid Instance

[ { "name": "John" }, 1, "hello", true, { "name": "John" } ]

Valid An empty array value is valid Instance

[]

Valid A non-array value is valid Instance

"Hello World"

A schema that allows array instances to contain duplicate items Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "uniqueItems": false
}