JSON Schema to Pydantic
Learn how to convert JSON Schema definitions into Pydantic models for runtime validation in Python. Pydantic uses Python type annotations to define data schemas that are validated at runtime — making it the natural Python counterpart to JSON Schema. This reference covers every JSON Schema type and its Pydantic equivalent.
What Is Pydantic?
Pydantic is the most widely used data validation library for Python. It provides runtime validation based on Python type annotations — you define a model class that inherits from BaseModel, annotate fields with Python types, and Pydantic automatically validates, coerces, and serializes data. When you pass JSON data to a Pydantic model, it validates every field and produces a clean Python object — or raises a ValidationError with detailed information about what went wrong.
Pydantic is the foundation of modern Python API frameworks like FastAPI and is widely used for configuration management, data processing pipelines, and any application that needs to validate external data. JSON Schema and Pydantic share the same design philosophy: describe and validate data structures. Converting JSON Schema to Pydantic models lets you use standards-based schema definitions with Pythonic code.
LangStop's JSON to Python tool can generate Python dataclasses from sample JSON, which you can then adapt into full Pydantic models by switching the base class and adding validation.
JSON Schema to Pydantic Mapping
Pydantic models use Python type annotations that map cleanly to JSON Schema types. Here is the complete mapping:
string → str
A JSON Schema stringmaps to Python's str type. Pydantic automatically coerces input to a string where possible. String constraints like minLength and maxLengthcan be enforced using Pydantic's Field() or custom validators.
# JSON Schema
{ "type": "string", "minLength": 1, "maxLength": 100 }
# Pydantic
from pydantic import BaseModel, Field
class UserModel(BaseModel):
name: str = Field(..., min_length=1, max_length=100)number → float / int
JSON Schema number maps to float, and integer maps to int. Pydantic will coerce compatible types — for example, the integer 42 will be accepted for a float field. Constraints like minimum and maximum are supported via Field().
# JSON Schema
{ "type": "integer", "minimum": 0, "maximum": 100 }
# Pydantic
from pydantic import BaseModel, Field
class ScoreModel(BaseModel):
score: int = Field(..., ge=0, le=100)boolean → bool
Direct one-to-one mapping. JSON Schema boolean becomes Python bool.
# JSON Schema
{ "type": "boolean" }
# Pydantic
from pydantic import BaseModel
class FeatureModel(BaseModel):
is_active: boolarray → List[T]
JSON Schema array with items maps to List[element_type]using Python's typing.List (or listin Python 3.9+). Array length constraints use Pydantic's Field() with min_length and max_length.
# JSON Schema
{
"type": "array",
"items": { "type": "string" },
"minItems": 1
}
# Pydantic
from typing import List
from pydantic import BaseModel, Field
class TagsModel(BaseModel):
tags: List[str] = Field(..., min_length=1)object → BaseModel
Each JSON Schema object maps to a Pydantic model class that inherits from BaseModel. Properties become annotated fields on the class. Nested objects become nested Pydantic model classes.
# JSON Schema
{
"type": "object",
"properties": {
"id": { "type": "integer" },
"name": { "type": "string" },
"email": { "type": "string" }
},
"required": ["id", "name"]
}
# Pydantic
from pydantic import BaseModel
from typing import Optional
class UserModel(BaseModel):
id: int
name: str
email: Optional[str] = Nonerequired → Required Field (No Default)
In Pydantic, a field is required if it has no default value. Fields listed in JSON Schema's required array become fields without defaults (required in Pydantic). Fields not in required become Optional[T] with a default of None, or use Field(default=None).
# JSON Schema
{
"type": "object",
"properties": {
"email": { "type": "string" },
"phone": { "type": "string" }
},
"required": ["email"]
}
# Pydantic
from pydantic import BaseModel
from typing import Optional
class ContactModel(BaseModel):
email: str # required — no default value
phone: Optional[str] = None # optional — defaults to Noneenum → Enum
JSON Schema enum maps to a Python Enum class (or StrEnum in Python 3.11+). For string enums, inherit from str and Enum to get JSON serialization that outputs strings. Pydantic accepts both enum members and their values when parsing.
# JSON Schema
{ "type": "string", "enum": ["draft", "published", "archived"] }
# Pydantic
from enum import Enum
class Status(str, Enum):
DRAFT = "draft"
PUBLISHED = "published"
ARCHIVED = "archived"
from pydantic import BaseModel
class ArticleModel(BaseModel):
status: Statusformat: date-time → datetime
JSON Schema uses the format keyword to specify semantic types like dates and times. The date-timeformat maps to Python'sdatetime.datetime. Pydantic automatically parses ISO 8601 date-time strings into datetime objects. Other formats like date, time, uri, and email also have Pydantic equivalents.
# JSON Schema
{ "type": "string", "format": "date-time" }
# Pydantic
from datetime import datetime
from pydantic import BaseModel
class EventModel(BaseModel):
created_at: datetime
# Pydantic automatically parses ISO 8601 strings:
# {"created_at": "2026-06-17T10:30:00Z"}
# → datetime(2026, 6, 17, 10, 30, tzinfo=timezone.utc)$ref → Nested BaseModel
JSON Schema $ref references map to nested Pydantic model classes. Each referenced definition becomes its own BaseModel, and the referencing field uses that model as its type annotation. For recursive schemas (self-referencing), use the from __future__ import annotations approach or ForwardRef.
# JSON Schema
{
"type": "object",
"properties": {
"user": { "$ref": "#/$defs/User" }
},
"$defs": {
"User": {
"type": "object",
"properties": {
"name": { "type": "string" }
}
}
}
}
# Pydantic
from pydantic import BaseModel
class UserModel(BaseModel):
name: str
class DocumentModel(BaseModel):
user: UserModelRecommended Workflow
Here is how to go from JSON Schema to working Pydantic models using LangStop tools:
1. Create or Infer a JSON Schema
Use the JSON Schema GUI Builder to design a schema visually, or the JSON to JSON Schema tool to infer one from sample data.
2. Generate Python Dataclasses from JSON
Use the JSON to Python tool to generate dataclasses from sample JSON. The generated code gives you a head start — then adapt it to Pydantic by changing the base class and adding validation.
3. Convert to Pydantic Models
Change the base class from object to BaseModel, add Field() validators for JSON Schema constraints, and switch any Optional annotations as needed using the mapping guide above.
4. Use in Your Python Project
Install pydantic from pip and import your model. Call ModelName(**data) or ModelName.model_validate(data) to parse and validate JSON data.
Why Use Pydantic for JSON Schema?
Runtime Validation
Pydantic validates data at runtime, catching type errors, missing fields, and constraint violations when data enters your system — exactly like JSON Schema validators.
Type Coercion
Pydantic automatically coerces compatible types (e.g., string "42" to int 42), reducing boilerplate parsing code. You can control coercion strictness with Field(strict=True).
JSON Schema Generation
Pydantic models can generate their own JSON Schema via model.model_json_schema(). This means you can define your schema in Pydantic and export it as JSON Schema for interop with other tools.
FastAPI Integration
Pydantic is the validation backbone of FastAPI. Converting your JSON Schema to Pydantic models means automatic request/response validation, OpenAPI documentation, and interactive API docs.
Related Tools & References
Explore these LangStop tools to work with JSON Schema and Python models:
JSON to Python
Generate Python dataclasses and typed models from JSON for data processing and API clients.
JSON Schema GUI Builder
Visually build, edit, and manage JSON Schema with an intuitive drag-and-drop GUI — no manual schema writing needed.
JSON to JSON Schema
Generate standards-compliant JSON Schema from your JSON data for validation, documentation, and API contracts.
JSON to TypeScript Zod
Convert JSON to TypeScript Zod schemas with static type inference for runtime validation.
JSON to TypeScript Effect Schema
Convert JSON into composable Effect Schema for functional TypeScript validation and parsing.