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
formatconstraint 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:
-
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# orollama pull gemma4 # 6.6 GB, vision + tools# orollama pull llama3.1 # 4.9 GBIf you do not have Ollama installed yet, follow the Ollama installation guide first.
-
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" -
Check that Ollama is listening on the default port:
Terminal window curl http://localhost:11434/api/tagsYou 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.
import jsonfrom ollama import Client
MODEL = "qwen3"HOST = "http://localhost:11434"
EMAIL = """De: marie.dupont@acme-corp.frObjet: 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 respecterSCHEMA = { "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.
from typing import Literalfrom ollama import Clientfrom 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.ioObjet: Latence très élevée depuis hierVos 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 ligneticket = TicketSupport.model_validate_json(response["message"]["content"])print(ticket.categorie) # autocomplétion IDEprint(ticket.priorite)Real output:
performancehauteThe 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 Literalfrom 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.
from typing import Literal
from ollama import Clientfrom 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 fourniesresponse = 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émapersonne = 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/exceptfor 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) orenum(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
Nonefor the unknown. - The
formatparameter 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
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
Review
(0/0)Score by domain
A domain groups several guides and gets several questions, so its score is more reliable than a per-topic score, which often rests on a single question.
Summary
Strengths
No topic passed at 80% on at least two questions yet.
Weak areas
No topic below the pass mark.
Recommended next
Hints before you try again?
A new full quiz with random questions
Work again only on the questions you missed
FAQ
ollama --version). On older versions, only the format="json" mode (without a schema) exists. Also check that the model runs locally: the format parameter does not apply to Ollama's cloud models. Update by downloading the official script and running it after reading it (curl -fsSL https://ollama.com/install.sh -o ollama-install.sh, read it, then sh ollama-install.sh).email-validator's check, because the schema's format: "email" is only a hint and Ollama does not verify the format. Log the error, then plan a fallback (field set to None, retry with a more precise prompt).model_json_schema() will produce a JSON schema with $defs/$ref. Check the response with model_validate_json, especially on a small model.format="json" (magic string) only forces valid JSON, with no structure constraint → the model can invent the keys. format=<schema dict> constrains the structure. Prefer the schema as soon as you know the expected shape.None, the model can mark the unknown instead of inventing it. Without an instruction, it may invent values to respect the schema. Test on your own texts and count the invented values.