Skip to content
Tutorials Center
My learning

Topics

Lesson 12 of 39 ยท JSON Schema

JSON Schema for Objects and Arrays

Describe nested objects and lists with JSON Schema: properties, required, additionalProperties, dependentRequired, items, prefixItems, uniqueItems and contains, with runnable examples.

Real documents are trees: objects inside arrays inside objects. JSON Schema describes them by nesting schemas, so each level has its own properties or items. This lesson covers the keywords for both containers.

Objects

Keyword Meaning
properties schema for each named key
required keys that must be present
additionalProperties schema (or false) for keys not listed in properties
dependentRequired "if key A is present, key B must be too"
minProperties, maxProperties size limits

Setting additionalProperties: false closes the object, so misspelled keys fail. Giving a schema instead allows extras only if they match, which is useful for dictionaries.

Node.js Closed objects and dictionaries

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

dependentRequired

JSON
{
  "type": "object",
  "properties": { "card": { "type": "string" }, "cvv": { "type": "string" } },
  "dependentRequired": { "card": ["cvv"] }
}

Supplying card without cvv fails, while supplying neither is fine.

Node.js dependentRequired

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Nested objects

Nest a schema anywhere a schema is expected. Error paths show the exact location, which is vital for large documents.

Node.js A nested order

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Arrays

Keyword Meaning
items schema every element must match (beyond prefixItems)
prefixItems positional schemas, i.e. a tuple
minItems, maxItems length limits
uniqueItems all elements must differ
contains at least one element must match

A list of numbers is {"type": "array", "items": {"type": "number"}}. A tuple such as a coordinate pair uses prefixItems, and items: false forbids anything after the listed positions.

Node.js Lists, tuples and uniqueness

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

(In the older draft-07, tuples used items as an array; 2020-12 renamed that to prefixItems. Check your validator's draft.)

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does additionalProperties false do?

    It closes the object so extra or misspelled keys fail validation.
  2. 2. How do you describe a pair like [latitude, longitude] in 2020-12?

    prefixItems gives positional schemas for a tuple.
  3. 3. What does dependentRequired { "card": ["cvv"] } mean?

    It expresses a conditional requirement between properties.
  4. 4. What does contains check?

    contains requires one or more elements to match its schema.

Summary

  • properties, required and additionalProperties shape objects; false closes them.
  • dependentRequired links the presence of keys.
  • items, prefixItems, length limits, uniqueItems and contains shape arrays.
  • Nest schemas freely; error paths pinpoint the bad value.

Next: Composition, references and conditionals