1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
|
JSON Schema
===========
``msgspec`` provides a few utilities for generating `JSON Schema`_
specifications from msgspec-compatible :doc:`types <supported-types>` and
:doc:`constraints <constraints>`.
- `msgspec.json.schema`: generates a complete JSON Schema for a single type.
- `msgspec.json.schema_components`: generates JSON schemas for multiple types,
along with a corresponding ``components`` mapping. This is mainly useful when
generating multiple schemas to include in a larger specification like OpenAPI_.
The generated schemas are compatible with `JSON Schema`_ 2020-12 and OpenAPI_
3.1.
Example
-------
.. code-block:: python
import msgspec
from msgspec import Struct, Meta
from typing import Annotated, Optional
# A float constrained to values > 0
PositiveFloat = Annotated[float, Meta(gt=0)]
class Dimensions(Struct):
"""Dimensions for a product, all measurements in centimeters"""
length: PositiveFloat
width: PositiveFloat
height: PositiveFloat
class Product(Struct):
"""A product in a catalog"""
id: int
name: str
price: PositiveFloat
tags: set[str] = set()
dimensions: Optional[Dimensions] = None
# Generate a schema for a list of products
schema = msgspec.json.schema(list[Product])
# Print out that schema as JSON
print(msgspec.json.encode(schema))
.. code-block:: json
{
"type": "array",
"items": {"$ref": "#/$defs/Product"},
"$defs": {
"Dimensions": {
"title": "Dimensions",
"description": "Dimensions for a product, all measurements in centimeters",
"type": "object",
"properties": {
"length": {"type": "number", "exclusiveMinimum": 0},
"width": {"type": "number", "exclusiveMinimum": 0},
"height": {"type": "number", "exclusiveMinimum": 0}
},
"required": ["length", "width", "height"]
},
"Product": {
"title": "Product",
"description": "A product in a catalog",
"type": "object",
"properties": {
"id": {"type": "integer"},
"name": {"type": "string"},
"price": {"type": "number", "exclusiveMinimum": 0},
"tags": {
"type": "array",
"items": {"type": "string"},
"default": [],
},
"dimensions": {
"anyOf": [{"type": "null"}, {"$ref": "#/$defs/Dimensions"}],
"default": null,
}
},
"required": ["id", "name", "price"]
}
}
}
.. _JSON Schema: https://json-schema.org/
.. _OpenAPI: https://www.openapis.org/
|
