Skip to content
,

Ollama Structured Outputs: Get Reliable JSON with Schemas (Pydantic, Zod)

6–10 minutes
Woman holding a card reading JSON, hook perfect JSON every time

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.

TL;DR

  • Any valid JSON: add "format": "json" to /api/chat or /api/generate.
  • Exact shape: pass a JSON schema object as format. In Python use format=MyModel.model_json_schema(), then MyModel.model_validate_json(...).
  • Best results: also describe the schema in the prompt and set temperature to 0.
  • OpenAI SDK: use response_format against http://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

Free weekly email

Get new AI guides every week

One short weekly email with our newest local AI, ComfyUI and AI tool guides. No spam, no pop-ups, just the good stuff.

Free. Unsubscribe anytime in one click. We only use your email to send this newsletter. See our privacy policy.

Woman holding a card reading JSON, hook perfect JSON every time