Serialize Pydantic Models with model_dump
model_dump turns a Pydantic model into a plain Python dict, bridging typed objects and JSON serializers in FastAPI endpoints. Call it when you need raw data before returning a response. Do not confuse it with model_dump_json, which emits a string, not a dict.
WHY IT EXISTS: FastAPI and modern Python APIs depend on Pydantic models to validate incoming requests and structure outgoing responses. These models are rich Python objects carrying metadata, methods, and strict types. However, HTTP clients, databases, and message queues speak in plain dictionaries and JSON, not custom class instances. model_dump exists to collapse that typed object back into primitive Python data without writing brittle manual field copying.
THE MENTAL MODEL: Treat model_dump as a translator that flattens a structured object into a plain dictionary. It is the inverse of model validation. Validation takes raw JSON or a dict and enriches it into a type-safe object; model_dump strips away the type machinery and returns the raw payload. It does not produce a JSON string. It produces the Python data structure you would hand to a JSON encoder.
HOW IT WORKS: Calling instance.model_dump() iterates over the model fields and returns a dictionary. By default it runs in Python mode, preserving non-JSON-native types such as datetime, Decimal, or UUID as their original Python objects. You can change behavior with parameters. Passing mode='json' coerces those types into JSON-compatible strings and numbers. Other flags include exclude to drop fields, include to whitelist them, and by_alias to use field aliases instead of internal attribute names.
WHEN TO USE IT: Reach for model_dump whenever you cross the boundary from Pydantic's typed world into plain data. Common scenarios include logging model contents, converting a model to a dict before passing it to a SQLAlchemy query or a third-party SDK, manually constructing a JSONResponse in FastAPI, or caching model data in Redis as a hash. Anytime a library expects a mapping rather than an object, model_dump is the exit ramp.
WHEN NOT TO USE IT: Do not use it when FastAPI can serialize automatically; returning the model directly from a path operation is cleaner and lets FastAPI handle encoding. Avoid it if you actually need a JSON string, because model_dump_json is the correct tool for that. Also skip manual dumping when you need to preserve complex custom types that lose meaning in JSON form unless you have configured custom serializers.
ONE CANONICAL EXAMPLE: Imagine a FastAPI endpoint that receives an order, enriches it with internal metadata, and publishes it to a message queue. The queue client expects a plain dictionary. You call enriched_order.model_dump(mode='json') to obtain a dict with ISO-format timestamps and stringified enums, then pass that dict directly to the publisher. If you had used the default mode, the datetime field would remain a datetime object and the publisher's JSON encoder might fail or behave inconsistently.
Get five bites like this every day.
Tezvyn delivers a daily feed of 60-second tech bites with quizzes to lock in what you learn.