Skip to content
Tutorials Center
My learning

Topics

Lesson 13 of 39 ยท JSON Schema

JSON Schema Composition, $ref and Conditionals

Combine and reuse JSON Schemas with allOf, anyOf, oneOf, not, $ref, $defs and if/then/else, including discriminated unions and reusable definitions, with runnable examples.

Small schemas become big ones. This lesson shows how to reuse parts with $ref, combine rules with allOf, anyOf, oneOf and not, and make rules depend on the data with if/then/else.

$defs and $ref

Put reusable schemas under $defs, and point to them with $ref. A reference such as "#/$defs/address" is a JSON Pointer into the same document: # is the document root, then each / descends into a key.

Node.js Reusing an address schema

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.

References can also point to other files or URLs ("$ref": "https://example.com/schemas/address.json"), and a schema can use $id to name itself. Our stand-in validator supports only local #/... references, but real libraries handle the rest.

allOf, anyOf, oneOf, not

Keyword Passes when the data matches...
allOf all listed schemas
anyOf at least one
oneOf exactly one
not the schema does not match

allOf is how you extend a base schema: {"allOf": [{"$ref": "#/$defs/base"}, {"properties": {...}}]}. anyOf suits "string or number". oneOf suits mutually exclusive shapes, but be careful: if two options can both match, oneOf fails.

Node.js Combining schemas

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.

The 3 case fails oneOf because it is both a number and an integer. Use anyOf, or make the options disjoint.

Discriminated unions

A common pattern: an object whose type field decides the rest of its shape. With oneOf and a const on the tag, exactly one branch can match, and error messages stay readable.

Node.js Shapes by a type tag

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.

if, then, else

if/then/else applies rules conditionally: if the data matches if, it must also match then; otherwise it must match else. Failing the if alone never causes an error.

Node.js Conditional requirements

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.

Which tool when?

flowchart TD
  A["Need to combine rules?"] --> B{"Must ALL apply?"}
  B -->|yes| C["allOf"]
  B -->|no| D{"Exactly one of several shapes?"}
  D -->|yes| E["oneOf with a const tag"]
  D -->|no| F{"At least one?"}
  F -->|yes| G["anyOf"]
  F -->|no| H["if / then / else or not"]

Reach for the simplest keyword that expresses the rule.

Prefer if/then/else or a tag with oneOf over huge anyOf lists: errors become much easier to read.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does "$ref": "#/$defs/address" point to?

    It is a JSON Pointer into the schema document itself.
  2. 2. Why does oneOf [number, integer] fail for the value 3?

    oneOf requires exactly one match; 3 matches both options.
  3. 3. Which keyword extends a base schema with more rules?

    allOf requires every listed schema to match, so it composes a base with extras.
  4. 4. What happens when the data fails the if schema and there is no else?

    Failing if never causes an error; only then/else add constraints.

Summary

  • $defs and $ref remove repetition.
  • allOf combines, anyOf needs one match, oneOf exactly one, not negates.
  • Tag unions with const and oneOf; use if/then/else for conditional rules.
  • Choose the simplest keyword that expresses the rule, for readable errors.

Next: XML syntax