---

name: json-schema

prettier-ignore

description: Use when working with JSON Schema for validation, OpenAPI schemas, type definitions, and data structure specification

JSON Schema

Quick Start

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["id", "email"],
  "properties": {
    "id": { "type": "string", "format": "uuid" },
    "email": { "type": "string", "format": "email" },
    "age": { "type": "integer", "minimum": 0, "maximum": 150 },
    "role": { "enum": ["admin", "user", "guest"] },
    "tags": { "type": "array", "items": { "type": "string" } }
  }
}

Type Keywords

Type	Validation Keywords
string	minLength, maxLength, pattern, format
number/integer	minimum, maximum, exclusiveMinimum, multipleOf
array	items, minItems, maxItems, uniqueItems
object	properties, required, additionalProperties

Composition

{
  "allOf": [{ "$ref": "#/$defs/Base" }, { "properties": { "extra": {} } }],
  "oneOf": [{ "type": "string" }, { "type": "number" }],
  "anyOf": [{ "minimum": 0 }, { "maximum": 100 }],
  "not": { "type": "null" }
}

References

{
  "$defs": {
    "Address": {
      "type": "object",
      "properties": { "street": { "type": "string" } }
    }
  },
  "properties": {
    "billing": { "$ref": "#/$defs/Address" },
    "shipping": { "$ref": "#/$defs/Address" }
  }
}

Common Formats

date-time, date, time, email, uri, uuid, ipv4, ipv6, hostname

OpenAPI 3.1 Notes

• OpenAPI 3.1 uses JSON Schema 2020-12
• Use nullable via type: ["string", "null"]
• example for single example, examples for multiple
• $ref can have siblings in 3.1 (not in 3.0)