JSON Schema =========== ``msgspec`` provides a few utilities for generating `JSON Schema`_ specifications from msgspec-compatible :doc:`types ` and :doc:`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/