Skip to content
Français
Account: not signed in, sync available My learning
Select theme
Français
Lire en français

Structured outputs with Ollama: JSON Schema and Pydantic locally

17 min read
Improve this page

You ask an LLM to fill in a form as JSON, and it sometimes sends back an introductory text such as "Here is the requested JSON:" before the block, invents an extra quote or forgets a comma. Your pipeline breaks. Ollama's structured outputs solve this problem: you give the model a schema, that is, the list of expected fields and their type, and generation is constrained to respect it.

The lesson Advanced Ollama already showed the basic case: format= receives Model.model_json_schema() and model_validate_json validates the response. This lesson starts from there and covers what it does not teach: the hand-written JSON schema, enum and Literal for classification, nullable fields, the limits of JSON that is valid but invented, and the choice of model.

What you will learn

  • What the format constraint guarantees, and what it does not guarantee (including which models it applies to)
  • How to force Ollama to respect a hand-written JSON Schema (the minimalist approach)
  • How to declare optional fields (str | None) and constrained values (Literal) with Pydantic
  • Where the model goes wrong despite the schema: the schema fixes the shape of the response, not the correctness of its content
  • How to compare two models on your own schema

Why structured outputs change everything

Without a schema, you had to ask "return only JSON" in the prompt, then wrap json.loads() in a try/except, because the result might not be JSON. Since Ollama 0.5, the format parameter accepts a JSON schema. On the server side, Ollama then forces generation, token by token (a token is a piece of a word), to respect that schema, even on small models.

The constraint applies to the text the model writes, not to the moment its response stops: if num_predict (the token limit seen in the advanced lesson) cuts the response off midway, the JSON remains incomplete. Ollama's documentation also advises passing the schema in the prompt and lowering the temperature (to 0, for example) to limit variation from one call to the next.

In practice, structured outputs let you:

  • extract entities from free text (email, ticket, CV) as typed JSON;
  • classify an input into a category chosen from a predefined list (an enumeration);
  • feed local agents whose code directly consumes the data structures;
  • get the structured description of an image (see the Vision guide).

Prerequisites and installation

To follow this guide, you need:

  1. An Ollama running locally with a chat model. Three suitable chat models, with the sizes given on ollama.com/library:

    Terminal window
    ollama pull qwen3 # 5.2 GB
    # or
    ollama pull gemma4 # 6.6 GB, vision + tools
    # or
    ollama pull llama3.1 # 4.9 GB

    If you do not have Ollama installed yet, follow the Ollama installation guide first.

  2. A Python project with the following dependencies (pinned for reproducibility):

    pyproject.toml
    [project]
    name = "lab-ollama-structured"
    version = "0.1.0"
    requires-python = ">=3.10"
    dependencies = [
    "ollama==0.6.3",
    "pydantic[email]==2.14.3",
    ]
    Terminal window
    uv sync
    # or: pip install "ollama==0.6.3" "pydantic[email]==2.14.3"
  3. Check that Ollama is listening on the default port:

    Terminal window
    curl http://localhost:11434/api/tags

    You should see the list of installed models.

Method 1: raw JSON Schema (the foundation)

This is the most direct method: you write the JSON schema by hand and pass it to the format parameter of the Ollama client.

Take a concrete case: you receive a support email and you want to extract the key information as JSON, to route it to the right team.

The email, the prompt and the schema of this example are in French, so the model answers in French. The field names read as follows: expediteur_nom is the sender's name, expediteur_email the sender's email, entreprise the company, numero_client the customer number, categorie the category, priorite the priority and resume the summary. The category values mean authentication, billing, performance, bug and other; the priority values mean low, normal, high and critical.

01-json-schema.py
import json
from ollama import Client
MODEL = "qwen3"
HOST = "http://localhost:11434"
EMAIL = """
De: marie.dupont@acme-corp.fr
Objet: Problème avec l'API key
Bonjour, mes appels API retournent 401 Unauthorized depuis ce matin.
Numéro client : ACME-4271. Plan Pro, carte à jour.
Marie Dupont, Lead Developer chez ACME Corp
"""
# Le schéma JSON : la structure que le modèle DOIT respecter
SCHEMA = {
"type": "object",
"properties": {
"expediteur_nom": {"type": "string"},
"expediteur_email": {"type": "string", "format": "email"},
"entreprise": {"type": "string"},
"numero_client": {"type": "string"},
"categorie": {
"type": "string",
"enum": ["authentification", "facturation", "performance", "bug", "autre"],
},
"priorite": {"type": "string", "enum": ["basse", "normale", "haute", "critique"]},
"resume": {"type": "string"},
},
"required": ["expediteur_nom", "expediteur_email", "entreprise", "categorie", "priorite", "resume"],
}
client = Client(host=HOST)
response = client.chat(
model=MODEL,
messages=[
{"role": "system", "content": "Tu extrais les informations d'un email de support en JSON."},
{"role": "user", "content": EMAIL},
],
format=SCHEMA, # le schéma passe ici
options={"temperature": 0},
)
raw = response["message"]["content"]
print(raw)
# Le schéma contraint la génération : json.loads() réussit, sauf réponse tronquée.
parsed = json.loads(raw)
print(parsed["categorie"], "→", parsed["priorite"])

Save the script in the project folder, then run it with uv run 01-json-schema.py: uv finds the environment created by uv sync and does not make you activate it. The same command works for the following scripts.

With qwen3, the model thinks before it answers, and this is the default behavior: without the think parameter, the message.thinking field of the response contains that reasoning. The script above keeps this behavior. Passing think=False to client.chat turns it off and cuts the wait sharply: 2.5 s instead of 29.8 s for the same short question. This measurement comes from an Intel Core i7-12650H processor (16 threads, no GPU), with qwen3 at 8 billion parameters and Ollama 0.40.16. It covers a call without format: it was not redone with a schema.

Real output (Ollama 0.40.16, ollama SDK 0.6.3, qwen3 at 8 billion parameters on processor only):

{
"expediteur_nom": "Marie Dupont",
"expediteur_email": "marie.dupont@acme-corp.fr",
"entreprise": "ACME Corp",
"categorie": "performance",
"priorite": "haute",
"resume": "Problème avec l'API key",
"numero_client": "ACME-4271"
}

The JSON respects the schema, but its content may vary from one run to the next. Here, the model classified an authentication problem (a 401 error) as performance, whereas the right value is authentification: the schema does not guarantee the correctness of the values. In this run, the keys do not come out in the schema's order either; do not rely on that order.

Method 2: Pydantic (the most practical day to day)

Writing a JSON schema by hand for every output is long and prone to typos. You already know the remedy, seen in the lesson Advanced Ollama: describe the structure as a Pydantic class and derive the schema from it.

The script below uses four elements of Pydantic and Python that the advanced lesson did not use. EmailStr is a type that checks that a string looks like an email address, thanks to the pydantic[email] extra installed above. Literal[...] limits a field to a list of values (we come back to it in method 3). str | None = None makes a field optional. As for Field(description=...), it adds a description to the field in the schema.

02-pydantic.py
from typing import Literal
from ollama import Client
from pydantic import BaseModel, EmailStr, Field
MODEL = "qwen3"
HOST = "http://localhost:11434"
class TicketSupport(BaseModel):
"""Ticket extrait d'un email entrant."""
expediteur_nom: str
expediteur_email: EmailStr
expediteur_role: str | None = None
entreprise: str
numero_client: str | None = None
categorie: Literal["authentification", "facturation", "performance", "bug", "autre"]
priorite: Literal["basse", "normale", "haute", "critique"]
resume: str = Field(description="Synthèse en 1-2 phrases du problème exposé.")
EMAIL = """
De: paul.martin@datalab.io
Objet: Latence très élevée depuis hier
Vos endpoints /v1/embeddings prennent 8-12 secondes depuis hier soir.
Numéro client : DTL-998. Paul, CTO Datalab
"""
client = Client(host=HOST)
response = client.chat(
model=MODEL,
messages=[{"role": "user", "content": EMAIL}],
# Pydantic génère le JSON Schema automatiquement
format=TicketSupport.model_json_schema(),
options={"temperature": 0},
)
# Validation + objet typé en une ligne
ticket = TicketSupport.model_validate_json(response["message"]["content"])
print(ticket.categorie) # autocomplétion IDE
print(ticket.priorite)

Real output:

performance
haute

The expediteur_role: str | None = None field is a nullable field: Pydantic describes it in the schema as a string or null, and does not put it in required. The model can therefore answer null when the email does not give the information, which is better than an invented value (see the trap below). An invalid EmailStr, on the other hand, raises an exception at validation. The Function calling guide (in French) uses the same mechanism to validate a tool's arguments.

Method 3: enumerations and constrained types

Classification is a common use case. An LLM can categorize a text, but it tends to invent new categories or to word them its own way. With Literal[...] (Pydantic) or enum (JSON Schema), generation is limited to your list.

from typing import Literal
from pydantic import BaseModel
class Classification(BaseModel):
sentiment: Literal["positif", "neutre", "negatif"]
urgence: Literal["faible", "moyenne", "haute"]
departement_concerne: Literal["support", "ventes", "tech", "rh", "autre"]

Your downstream code therefore does not receive an invented category. It can, however, receive the wrong category from the list, like the 401 classified as performance above.

The trap: the schema guarantees structure, not truthfulness

The schema imposes the shape of the response, not the correctness of its content. To see this, let us ask for information that we do not give to the model. This script runs on its own.

03-limits.py
from typing import Literal
from ollama import Client
from pydantic import BaseModel, EmailStr
client = Client(host="http://localhost:11434")
class Personne(BaseModel):
nom: str
email: EmailStr
age: int
pays: Literal["France", "Belgique", "Suisse", "Canada", "Autre"]
# Prompt pauvre : on demande des infos non fournies
response = client.chat(
model="qwen3",
messages=[{"role": "user", "content": "Donne-moi les informations d'un utilisateur."}],
format=Personne.model_json_schema(),
)
contenu = response["message"]["content"]
print(contenu)
# Pydantic valide la structure : aucune exception si le JSON respecte le schéma
personne = Personne.model_validate_json(contenu)
print(personne)

Real output (Ollama 0.40.16, qwen3, processor only):

{
"nom": "Jean Dupont", "email": "jean.dupont@example.com", "age": 30, "pays": "France"}
nom='Jean Dupont' email='jean.dupont@example.com' age=30 pays='France'

The first lines, up to the closing brace, are the model's raw response; the last line is the object that model_validate_json builds. The JSON is syntactically valid, and Pydantic raises no exception. But this data is purely invented: the model imagined a generic user (Jean Dupont, 30 years old, in France, with an address on example.com) to fill the schema. In production, these values would enter your database as real data.

Which model should you choose for structured outputs?

The format parameter applies to the chat models that your Ollama runs locally. It does not apply to Ollama's cloud models. Even locally, fidelity to the schema depends on the model and on your schema: a small model can respect the structure while inventing the values.

The guide offers qwen3 (5.2 GB file), gemma4 (6.6 GB for the latest tag) and llama3.1, sizes taken from ollama.com/library. Its scripts use qwen3, without that necessarily being the best choice for your case.

To compare two models on your case, run the same script with both and validate the output with Pydantic. Count the responses rejected by model_validate_json, which reveal a faulty structure or format, then re-read by hand a few responses whose correct value you know: Pydantic does not see a wrong value that is well formed. For memory and speed, ollama ps shows the memory used (SIZE column) and the processor or GPU split (PROCESSOR column), and ollama run --verbose <model> "<question>" shows eval rate, the speed in tokens per second.

Key takeaways

  • Structured outputs constrain generation to the schema; keep a try/except for the case of a truncated response.
  • Raw JSON Schema for a short schema; Pydantic as soon as it has several fields or the content must be validated.
  • Literal (Pydantic) or enum (JSON Schema) for classification: the model can no longer invent a category.
  • The schema constrains the structure, not the truthfulness: provide the source context in the prompt and allow None for the unknown.
  • The format parameter applies to local models, not to Ollama's cloud models.
  • Compare models on your schema: count Pydantic's rejections, then check by hand a few values whose answer you know.

Knowledge check

Check that you have the essentials of this guide. The questions cover only what was just explained here.

Knowledge check

Check what you have learned with this interactive quiz

6 questions
6 min
70% to pass

How it works

  • The timer starts when you click Start
  • Multiple choice, true/false and short answer questions
  • You can move between questions
  • Detailed results are shown at the end

Starts the quiz and the timer

FAQ