FAQs {#faqs-jsonschema}#

JSON Schema — Frequently Asked Questions#

JSON Schema is powerful, but it has quirks that often trip up even experienced developers. This FAQ collects the most common questions and pitfalls, with examples and corrected usage.

1. What is JSON Schema used for?#

JSON Schema is a vocabulary for describing and validating the structure of JSON documents.
It’s commonly used to validate API payloads, configuration files, and data exchange formats.

2. What’s the difference between JSON Schema draft-07, 2019-09, and 2020-12?#

• draft-07: widely supported, still common in tooling.
• 2019-09: introduced vocabularies, $defs, and unevaluatedProperties.
• 2020-12: refined vocabularies, anchors ($dynamicRef), and better extensibility.
  Check your tooling to see which draft it supports.

3. How do I define required vs optional properties?#

• Optional by default (properties are not required unless specified).
• Use required array to enforce presence.

type: object
properties:
  name:
    type: string
required: ["name"]

4. What’s the difference between properties, patternProperties, and additionalProperties?#

• properties: explicitly named keys.
• patternProperties: regex-based keys.
• additionalProperties: controls whether other, unspecified keys are allowed.

type: object
properties:
  id:
    type: string
patternProperties:
  "^x-":
    type: string
additionalProperties: false

5. Does additionalProperties default to false?#

No — the default is true.
If not specified, objects can include keys not listed in properties.

6. How do I allow null values?#

Use a union type with "null":

type: [string, "null"]

7. What’s the difference between enum and const?#

• enum: allows one of many predefined values.
• const: allows exactly one value.

enum: ["red", "green", "blue"]   # multiple choices
const: "red"                     # must be red

8. How does default work in JSON Schema?#

default is informative only — validators are not required to enforce it.
It’s meant for tools (e.g., code generators, form builders).

type: string
default: "guest"

9. What’s the difference between oneOf, anyOf, and allOf?#

• oneOf: matches exactly one subschema.
• anyOf: matches one or more.
• allOf: must match all subschemas (composition).

oneOf:
  - type: string
  - type: number

10. What is $ref and how does it work?#

$ref allows reuse of schema definitions.
It replaces the referencing object entirely.

$ref: '#/$defs/User'

Note: $ref cannot be combined with siblings (e.g., type or description).

11. What’s the difference between $defs and definitions?#

• definitions: older keyword (draft-07 and earlier).
• $defs: modern replacement (2019-09+).

$defs:
  User:
    type: object
    properties:
      id:
        type: string

12. How do I handle regex validation with pattern?#

Use pattern for regex string validation.
Remember: JSON Schema uses ECMA-262 regular expressions (JavaScript regex flavor).

type: string
pattern: "^[A-Za-z0-9_-]{3,16}$"

13. What’s the difference between minLength, minimum, and minItems?#

• minLength: strings.
• minimum: numbers.
• minItems: arrays.

type: array
items:
  type: string
minItems: 2

14. How do unevaluatedProperties and additionalProperties differ?#

• additionalProperties: applies only if properties/patternProperties don’t match.
• unevaluatedProperties: applies after all other keywords are evaluated.
  unevaluatedProperties is more powerful, but requires 2019-09+.

15. How does format work?#

format is a hint, not strict validation.
Examples: date-time, email, uuid.
Some validators enforce them, others ignore or allow extensions.

type: string
format: email

16. How do I specify arrays with fixed-length tuples?#

Use an array of schemas in items.

type: array
items:
  - type: string   # first element
  - type: number   # second element
minItems: 2
maxItems: 2

17. How do I enforce unique items in an array?#

Use uniqueItems: true.

type: array
items:
  type: string
uniqueItems: true

18. What’s the purpose of $id in JSON Schema?#

$id assigns a URI to a schema. Useful for referencing schemas across files or packages.

$id: "https://example.com/schemas/user.json"
type: object
properties:
  id:
    type: string

19. How does $dynamicRef differ from $ref?#

• $ref: static reference.
• $dynamicRef: allows reference resolution to be deferred until runtime, useful in extensible vocabularies (2020-12+).

20. Do validators always enforce everything in JSON Schema?#

Not necessarily.

• default, title, description are annotations (informative).
• type, properties, required, etc. are constraints (enforced).
  Always check if your validator distinguishes between the two.