Asking a local model to “reply in JSON” works most of the time. Then one day it adds a friendly sentence before the JSON, forgets a field or wraps everything in markdown, and your script crashes.
Ollama’s structured outputs fix that. You pass a JSON schema in the format field, and Ollama constrains the model so the reply matches the schema.
This guide shows JSON mode and full schemas with curl, Python (Pydantic) and JavaScript (Zod), with real examples for data extraction, classification and images. It also covers the OpenAI-compatible way and how to fix the common problems.
- Any valid JSON: add
"format": "json"to/api/chator/api/generate. - Exact shape: pass a JSON schema object as
format. In Python useformat=MyModel.model_json_schema(), thenMyModel.model_validate_json(...). - Best results: also describe the schema in the prompt and set
temperatureto 0. - OpenAI SDK: use
response_formatagainsthttp://localhost:11434/v1. - Local only: Ollama’s docs note that its cloud does not currently support structured outputs.
New to Ollama? My Ollama guide covers install, models, commands and fixes in one place.
What Structured Outputs Do
Normally a model can write any token next. With a schema, Ollama only lets it produce output that fits your JSON structure: the right keys, the right types and valid brackets. You get:
- Valid JSON every time, with no “Sure! Here is your JSON:” text around it.
- The fields you asked for, with the types you defined.
- Simpler code. Parse and validate, with no regex clean-up.
It works with almost any model you run locally, because the constraint is applied while the text is generated. It does not depend on the model having special training. A smarter model still fills the fields with better content, though.
JSON Mode: format “json”
The simplest option guarantees valid JSON but not a specific shape:
curl -s http://localhost:11434/api/chat -d '{
"model": "llama3.2",
"messages": [{"role": "user", "content": "Tell me about Canada in one line. Reply as JSON."}],
"stream": false,
"format": "json"
}'
Always mention JSON in the prompt too, so the model knows what to put in it. JSON mode is fine for quick tests. For real apps, use a schema.
Full Schema with curl
Pass a JSON schema object as format:
curl -s http://localhost:11434/api/chat -d '{
"model": "llama3.2",
"messages": [{"role": "user", "content": "Tell me about Canada."}],
"stream": false,
"options": {"temperature": 0},
"format": {
"type": "object",
"properties": {
"name": {"type": "string"},
"capital": {"type": "string"},
"languages": {"type": "array", "items": {"type": "string"}}
},
"required": ["name", "capital", "languages"]
}
}'
The reply’s message.content is a JSON string such as {"name": "Canada", "capital": "Ottawa", "languages": ["English", "French"]}. The same format field works on /api/generate. All endpoints are covered in my Ollama API guide.
Python with Pydantic
Writing schemas by hand gets tedious. In Python, define a Pydantic model, pass its schema, and validate the reply in one line:
pip install -U ollama pydantic
from ollama import chat
from pydantic import BaseModel
class Country(BaseModel):
name: str
capital: str
languages: list[str]
response = chat(
model="llama3.2",
messages=[{"role": "user", "content": "Tell me about Canada."}],
format=Country.model_json_schema(),
options={"temperature": 0},
)
country = Country.model_validate_json(response.message.content)
print(country.capital) # Ottawa
If the model somehow returns something that does not fit, model_validate_json raises a clear error instead of passing bad data along.
JavaScript with Zod
import ollama from 'ollama'
import * as z from 'zod'
const Country = z.object({
name: z.string(),
capital: z.string(),
languages: z.array(z.string()),
})
const response = await ollama.chat({
model: 'llama3.2',
messages: [{ role: 'user', content: 'Tell me about Canada.' }],
format: z.toJSONSchema(Country),
options: { temperature: 0 },
})
const country = Country.parse(JSON.parse(response.message.content))
console.log(country)
z.toJSONSchema() is built into Zod 4. Install both packages with npm i ollama zod.
Example: Extract Data from Text
Turn messy text (emails, notes, invoices) into clean records:
from ollama import chat
from pydantic import BaseModel
class Pet(BaseModel):
name: str
animal: str
age: int
color: str | None
favorite_toy: str | None
class PetList(BaseModel):
pets: list[Pet]
text = """I have two cats named Luna and Loki. Luna is 3, black, and loves her
feather wand. Loki is a 5 year old orange tabby. My dog Max is 2 and chews
tennis balls all day."""
response = chat(
model="llama3.2",
messages=[{"role": "user", "content": text}],
format=PetList.model_json_schema(),
options={"temperature": 0},
)
for pet in PetList.model_validate_json(response.message.content).pets:
print(pet)
Optional fields (str | None) let the model leave out details the text never mentions, instead of making them up. This pattern pairs nicely with local document workflows, such as chatting with PDFs locally.
Example: Classify with Enums
For sorting tickets, reviews or emails, limit the answer to fixed labels with Literal:
from typing import Literal
from pydantic import BaseModel
from ollama import chat
class Ticket(BaseModel):
category: Literal["billing", "bug", "feature_request", "other"]
urgency: Literal["low", "medium", "high"]
summary: str
msg = "The app crashes every time I export a PDF and I have a client demo in an hour!"
r = chat(model="llama3.2", messages=[{"role": "user", "content": msg}],
format=Ticket.model_json_schema(), options={"temperature": 0})
print(Ticket.model_validate_json(r.message.content))
# category='bug' urgency='high' summary='App crashes on PDF export before a client demo'
The model cannot invent a new category, because the schema only allows those values.
Example: Describe an Image as JSON
Vision models accept the same format field, which makes image tagging and cataloguing easy:
from typing import Literal
from pydantic import BaseModel
from ollama import chat
class ImageInfo(BaseModel):
summary: str
objects: list[str]
colors: list[str]
setting: Literal["Indoor", "Outdoor", "Unknown"]
text_content: str | None = None
r = chat(
model="gemma3",
messages=[{"role": "user", "content": "Describe this photo.", "images": ["photo.jpg"]}],
format=ImageInfo.model_json_schema(),
options={"temperature": 0},
)
print(ImageInfo.model_validate_json(r.message.content))
Use any vision model you have pulled (Gemma 3 or newer, Qwen VL, Llama vision and others). For more options, see the best local vision models.
OpenAI-Compatible response_format
Already using the OpenAI SDK? Point it at Ollama and use response_format:
from openai import OpenAI
from pydantic import BaseModel
client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")
class Country(BaseModel):
name: str
capital: str
languages: list[str]
completion = client.beta.chat.completions.parse(
model="llama3.2",
messages=[{"role": "user", "content": "Tell me about Canada."}],
response_format=Country,
temperature=0,
)
print(completion.choices[0].message.parsed)
This makes it easy to move code between OpenAI, Gemini and a local model. Compare with the cloud versions in my structured outputs guide for Claude, OpenAI and Gemini.
Structured Outputs vs Tool Calling
| Structured outputs | Tool calling | |
|---|---|---|
| Goal | Get the final answer in a fixed JSON shape | Let the model ask your code to run functions |
| Field | format |
tools |
| Model support | Works with almost any model | Needs a model with the tools tag |
| Best for | Extraction, classification, reports, image tags | Agents, live data, actions |
You can combine them: tools to gather data, then structured outputs for the final report. Tools are covered in my Ollama tool calling guide.
Tips for Reliable JSON
- Put the schema in the prompt too. Ollama’s docs recommend also passing the schema as text, which grounds the model’s content.
- Set temperature to 0 for consistent, repeatable results.
- Keep schemas flat and small. Deeply nested schemas with many optional fields confuse small models.
- Add field descriptions with
Field(description="...")in Pydantic. The model reads them. - Use enums (
Literal) wherever there is a fixed set of answers. - Raise the context for long inputs, since Ollama’s default may only be 4k tokens. See my context length guide.
- Always validate. Valid JSON is guaranteed, but sensible values are up to the model.
Troubleshooting
The JSON is valid but the values are wrong or made up
The schema controls the shape, not the truth. Use a bigger model, lower the temperature, make fields optional where the source may not have the data, and add “use null if unknown” to the prompt.
Output stops halfway and the JSON is cut off
You hit a length limit. Raise num_predict (or remove the limit), increase num_ctx, or ask for fewer items per request.
Thinking models return odd output
With reasoning models, the thinking goes in a separate field and the structured answer in content. If results look off, try turning thinking off for extraction jobs, or update Ollama to the newest version. See how to update Ollama.
Schema field seems ignored
Very advanced JSON schema features may not be fully enforced. Stick to the basics: type, properties, required, items and enum. Then validate with Pydantic or Zod.
“format” has no effect on a cloud model
Ollama’s docs say its cloud does not currently support structured outputs. Run the model locally instead.
FAQ
What is the difference between format “json” and a schema?
"json" only guarantees valid JSON in any shape. A schema also forces the exact keys and types you define.
Which models support structured outputs?
Almost any local model, because the constraint is applied while generating. Larger, instruction-tuned models fill the fields more accurately.
Does it slow generation down?
Barely. Often it is faster overall, because the model does not waste tokens on extra text.
Can I stream structured outputs?
Yes, but you only get valid JSON once the stream finishes. Join the chunks, then parse.
Does LM Studio support this?
Yes, through response_format on its OpenAI-compatible server. See my LM Studio API guide.
Sources
- Ollama docs: Structured outputs (format json and schema, Pydantic, Zod, vision example, tips, cloud note)
- Ollama API reference (format parameter on /api/chat and /api/generate)
- Pydantic documentation
- Zod: JSON Schema



