pydantic/docs/usage/schema.md

*Pydantic* allows auto creation of JSON Schemas from models:

```py
{!./examples/schema1.py!}
```
_(This script is complete, it should run "as is")_

Outputs:

```json
{!./examples/schema1.json!}
```

The generated schemas are compliant with the specifications:
[JSON Schema Core](https://json-schema.org/latest/json-schema-core.html),
[JSON Schema Validation](https://json-schema.org/latest/json-schema-validation.html) and
[OpenAPI](https://github.com/OAI/OpenAPI-Specification).

`BaseModel.schema` will return a dict of the schema, while `BaseModel.schema_json` will return a JSON string
representation of that.

Sub-models used are added to the `definitions` JSON attribute and referenced, as per the spec.

All sub-models (and their sub-models) schemas are put directly in a top-level `definitions` JSON key for easy re-use
and reference.

"sub-models" with modifications (via the `Field` class) like a custom title, description or default value,
are recursively included instead of referenced.

The `description` for models is taken from the docstring of the class or the argument `description` to
the `Field` class.

## Field customisation

Optionally the `Field` function can be used to provide extra information about the field and validations, arguments:

* `default` (positional argument), since the `Field` is replacing the field's default, its first
  argument is used to set the default, use ellipsis (``...``) to indicate the field is required
* `alias` - the public name of the field
* `title` if omitted `field_name.title()` is used
* `description` if omitted and the annotation is a sub-model, the docstring of the sub-model will be used
* `const` this field *must* take it's default value if it is present
* `gt` for numeric values (``int``, `float`, `Decimal`), adds a validation of "greater than" and an annotation
  of `exclusiveMinimum` to the JSON Schema
* `ge` for numeric values, adds a validation of "greater than or equal" and an annotation of `minimum` to the
  JSON Schema
* `lt` for numeric values, adds a validation of "less than" and an annotation of `exclusiveMaximum` to the
  JSON Schema
* `le` for numeric values, adds a validation of "less than or equal" and an annotation of `maximum` to the
  JSON Schema
* `multiple_of` for numeric values, adds a validation of "a multiple of" and an annotation of `multipleOf` to the
  JSON Schema
* `min_items` for list values, adds a corresponding validation and an annotation of `minItems` to the
  JSON Schema
* `max_items` for list values, adds a corresponding validation and an annotation of `maxItems` to the
  JSON Schema
* `min_length` for string values, adds a corresponding validation and an annotation of `minLength` to the
  JSON Schema
* `max_length` for string values, adds a corresponding validation and an annotation of `maxLength` to the
  JSON Schema
* `regex` for string values, adds a Regular Expression validation generated from the passed string and an
  annotation of `pattern` to the JSON Schema
* `**` any other keyword arguments (eg. `examples`) will be added verbatim to the field's schema

Instead of using `Field`, the `fields` property of [the Config class](model_config.md) can be used
to set all the arguments above except `default`.

The schema is generated by default using aliases as keys, it can also be generated using model
property names not aliases with `MainModel.schema/schema_json(by_alias=False)`.

## JSON Schema Types

Types, custom field types, and constraints (as `max_length`) are mapped to the corresponding
[JSON Schema Core](http://json-schema.org/latest/json-schema-core.html#rfc.section.4.3.1) spec format when there's
an equivalent available, next to [JSON Schema Validation](http://json-schema.org/latest/json-schema-validation.html),
[OpenAPI Data Types](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#data-types)
(which are based on JSON Schema), or otherwise use the standard `format` JSON field to define Pydantic extensions
for more complex `string` sub-types.

The field schema mapping from Python / Pydantic to JSON Schema is done as follows:

{!./.tmp_schema_mappings.html!}

## Top-level schema generation

You can also generate a top-level JSON Schema that only includes a list of models and all their related
submodules in its `definitions`:

```py
{!./examples/schema2.py!}
```
_(This script is complete, it should run "as is")_

Outputs:

```json
{!./examples/schema2.json!}
```

## Schema customization

You can customize the generated `$ref` JSON location, the definitions will still be in the key `definitions` and
you can still get them from there, but the references will point to your defined prefix instead of the default.

This is useful if you need to extend or modify JSON Schema default definitions location, e.g. with OpenAPI:

```py
{!./examples/schema3.py!}
```
_(This script is complete, it should run "as is")_

Outputs:

```json
{!./examples/schema3.json!}
```

It's also possible to extend/override the generated JSON schema in a model.

To do it, use the `Config` sub-class attribute `schema_extra`.

For example, you could add `examples` to the JSON Schema:

```py
{!./examples/schema4.py!}
```
_(This script is complete, it should run "as is")_

Outputs:

```json
{!./examples/schema4.json!}
```