Attach examples or descriptions to generated schemas
Documenting API contracts
Pydantic · Pipe
json_schema_extra
json_schema_extra adds custom properties to a Pydantic model's generated JSON Schema. Configure it with a dictionary or callable; its default is None.
How it works
Set json_schema_extra in a model's configuration to add custom properties to the JSON Schema generated for that model. The value can be a dictionary of schema data or a callable that modifies the schema.
Syntax
model_config = ConfigDict(json_schema_extra={...})Parameters
| Name | Type | Description |
|---|---|---|
json_schema_extra | JsonDict | JsonSchemaExtraCallable | None | Extra JSON Schema properties supplied as a dictionary, a callable, or None. |
Key points
- It adds custom properties to a model's generated JSON Schema.
- The setting supports a JSON-schema dictionary, a callable, or None.
- The default leaves the model without extra schema customization.
Common mistakes
- The value must be schema metadata supplied as a dictionary or through a callable; it is not validation logic.
- If omitted, no additional JSON Schema properties are supplied by this setting.
Example: Add JSON Schema metadata
from pydantic import BaseModel, ConfigDict
class Product(BaseModel):
model_config = ConfigDict(
json_schema_extra={"examples": [{"name": "Keyboard"}]}
)
name: str
print(Product.model_json_schema())Adds an example object to the generated JSON Schema.
When to use it
Add vendor extensions or other JSON Schema properties
Schema customization
Compute schema additions with a callable
Dynamic metadata
Interview questions
QWhat is json_schema_extra used for?
json_schema_extra is a model configuration option for adding extra JSON Schema properties. It accepts either a dictionary or a callable.
Follow-up: What happens when the option is omitted? It defaults to None, so this customization is not applied.
QHow do you configure json_schema_extra?
Use ConfigDict(json_schema_extra={...}) to attach metadata such as examples or descriptions to the generated schema. The extra data belongs to schema generation rather than runtime field validation.
Follow-up: How could dynamic metadata be supplied? Use the callable form so the schema customization can be computed or applied programmatically.
QWhat values can json_schema_extra accept?
The documented type is JsonDict | JsonSchemaExtraCallable | None. This means a dictionary, a supported callable, or no value can be used.
Follow-up: What should be checked when choosing the callable form? Verify the callable matches Pydantic's documented JsonSchemaExtraCallable type and modifies schema data as intended.
Related
ConfigDictBaseModel.model_json_schemaJsonDictJsonSchemaExtraCallable