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)
1---2name: json-schema3description: Use when working with JSON Schema for validation, OpenAPI schemas, type definitions, and data structure specification4---5
6# JSON Schema
7
8## Quick Start
9
10```json
11{
12 "$schema": "https://json-schema.org/draft/2020-12/schema",
13 "type": "object",
14 "required": ["id", "email"],
15 "properties": {
16 "id": { "type": "string", "format": "uuid" },
17 "email": { "type": "string", "format": "email" },
18 "age": { "type": "integer", "minimum": 0, "maximum": 150 },
19 "role": { "enum": ["admin", "user", "guest"] },
20 "tags": { "type": "array", "items": { "type": "string" } }
21 }
22}
23```
24
25## Type Keywords
26
27| Type | Validation Keywords |
28|------|---------------------|
29| `string` | `minLength`, `maxLength`, `pattern`, `format` |
30| `number/integer` | `minimum`, `maximum`, `exclusiveMinimum`, `multipleOf` |
31| `array` | `items`, `minItems`, `maxItems`, `uniqueItems` |
32| `object` | `properties`, `required`, `additionalProperties` |
33
34## Composition
35
36```json
37{
38 "allOf": [{ "$ref": "#/$defs/Base" }, { "properties": { "extra": {} } }],
39 "oneOf": [{ "type": "string" }, { "type": "number" }],
40 "anyOf": [{ "minimum": 0 }, { "maximum": 100 }],
41 "not": { "type": "null" }
42}
43```
44
45## References
46
47```json
48{
49 "$defs": {
50 "Address": {
51 "type": "object",
52 "properties": { "street": { "type": "string" } }
53 }
54 },
55 "properties": {
56 "billing": { "$ref": "#/$defs/Address" },
57 "shipping": { "$ref": "#/$defs/Address" }
58 }
59}
60```
61
62## Common Formats
63
64`date-time`, `date`, `time`, `email`, `uri`, `uuid`, `ipv4`, `ipv6`, `hostname`
65
66## OpenAPI 3.1 Notes
67
68- OpenAPI 3.1 uses JSON Schema 2020-12
69- Use `nullable` via `type: ["string", "null"]`
70- `example` for single example, `examples` for multiple
71- `$ref` can have siblings in 3.1 (not in 3.0)
majiayu000