AIForum.

How to Use Structured Outputs with Local Models via Ollama and JSON Schema

On this page

THE SHORT ANSWER

Ollama can constrain a local model's reply to a JSON schema you supply, so responses arrive as parseable data instead of prose. This guide covers the difference between JSON mode and schema mode, working cURL, Python, and JavaScript examples, schema design habits, validation, and the troubleshooting checks that keep a pipeline stable.
Quick facts

Ollama can constrain a local model’s reply to a JSON schema you supply, so the response arrives as parseable data rather than prose you have to clean up. The schema goes in the format field of a chat request, and the model returns output in the shape that schema defines. For anyone building extraction pipelines, automation, or API glue around a local model, that removes the most fragile part of the job: hoping the model returns valid JSON.

This guide explains what the feature does, walks through cURL, Python, and JavaScript examples based on Ollama’s documentation, and covers the schema design, validation, and troubleshooting details that decide whether a pipeline holds up in practice. It assumes you can already run a model locally through Ollama and are comfortable reading JSON.

JSON mode and schema mode are not the same thing

Ollama exposes structured output through a single format parameter, but that parameter accepts two different kinds of value. Passing "format": "json" turns on JSON mode: the model is asked to produce JSON, but nothing dictates which keys it uses. Passing an actual JSON Schema object instead constrains the output to that schema. Ollama’s documentation describes structured outputs as offering “more reliability and consistency than JSON mode,” which is the practical difference — JSON mode gives you well-formed JSON, while schema mode gives you well-formed JSON with the fields your code expects.

Ollama added structured outputs on December 6, 2024, and updated its Python and JavaScript libraries at the same time. The documented use cases are parsing data from documents, extracting data from images, structuring all language model responses, and getting more consistent output overall.

What you need before you start

  • A recent version of Ollama running locally, reachable at http://localhost:11434 by default.
  • An up-to-date client library if you call Ollama from code: pip install -U ollama for Python or npm i ollama for JavaScript. Older library versions do not expose the schema form of format.
  • A model pulled locally. Ollama’s own examples use llama3.1 and gpt-oss. Schema enforcement is a server capability, but how well a given model fills a complex schema still varies with model size and training.

One compatibility note matters if you were planning to move this workload to a hosted endpoint: Ollama’s documentation states that Ollama’s cloud currently does not support structured outputs. Schema-constrained generation in this workflow is a local-server feature.

Step 1: Send a schema with a cURL request

The raw HTTP API takes the schema directly in the request body. This example, adapted from Ollama’s documentation, asks for three fields and marks all of them required:

curl -X POST http://localhost:11434/api/chat 
  -H "Content-Type: application/json" 
  -d '{
    "model": "llama3.1",
    "messages": [{"role": "user", "content": "Tell me about Canada."}],
    "stream": false,
    "format": {
      "type": "object",
      "properties": {
        "name": {"type": "string"},
        "capital": {"type": "string"},
        "languages": {"type": "array", "items": {"type": "string"}}
      },
      "required": ["name", "capital", "languages"]
    }
  }'

The documented response for this request is a JSON object containing exactly those keys, for example:

{
  "capital": "Ottawa",
  "languages": ["English", "French"],
  "name": "Canada"
}

Note the key order: it does not have to match the order in your schema. Parse by key, not by position.

Ground the schema in the prompt as well

Ollama’s documentation recommends also passing the JSON schema as a string inside the prompt. The schema constrains decoding; the prompt tells the model what the fields mean. For fields such as invoice_total or risk_level, that extra context is what keeps values sensible rather than merely well-shaped.

Step 2: Use Pydantic from Python

The Python library accepts the schema as a plain dict, but Ollama recommends defining it with Pydantic and serializing it through model_json_schema(). That way the same class defines the schema you send and validates the response you get back:

from ollama import chat
from pydantic import BaseModel

class Country(BaseModel):
    name: str
    capital: str
    languages: list[str]

response = chat(
    model='llama3.1',
    messages=[{'role': 'user', 'content': 'Tell me about Canada.'}],
    format=Country.model_json_schema(),
)

country = Country.model_validate_json(response.message.content)
print(country.capital)

The model_validate_json() call is the standard Pydantic v2 way to turn the returned string into a typed object, and it fails loudly if the payload does not match the model. Treat that failure as a signal rather than an inconvenience: it is the boundary where a malformed response stops before it reaches your database.

Step 3: The JavaScript equivalent

The JavaScript library takes the same format value. The response content is a string, so parse it before use:

import ollama from 'ollama'

const response = await ollama.chat({
  model: 'llama3.1',
  messages: [{ role: 'user', content: 'Tell me about Canada.' }],
  format: {
    type: 'object',
    properties: {
      name: { type: 'string' },
      capital: { type: 'string' },
      languages: { type: 'array', items: { type: 'string' } }
    },
    required: ['name', 'capital', 'languages']
  }
})

console.log(JSON.parse(response.message.content))

Designing schemas a model can actually fill

The schema is a contract, and a contract with ambiguous terms produces disputes. A few habits pay off with local models in particular:

  • Prefer flat structures. Deeply nested objects increase the number of decisions the model makes and the number of ways a smaller model can go wrong. Splitting a complex extraction into two sequential calls with simpler schemas is usually more reliable than one call with a five-level tree.
  • Use enum for anything categorical. If a field must be one of "low", "medium", or "high", say so in the schema. Free-text categories invite creative spelling.
  • Be deliberate about required. Every required field is a field the model must fill even when the source text does not contain that information. For optional information, leave the field out of required and let the model omit it.
  • Describe fields in the prompt, not only in the schema. Keywords such as type and items constrain form; they do not explain that capital means the national capital.
  • Keep arrays bounded in practice. A schema that permits an unbounded array lets the model ramble. Where the domain allows it, state the expected count in the prompt.

Limitations and tradeoffs

Structured outputs constrain the shape of a response, not its truth. A schema-conformant object can still contain a wrong capital, a hallucinated invoice number, or a summary that misreads the source. Validation confirms the container, not the contents.

Three further constraints are worth planning around. First, as noted above, Ollama’s cloud does not currently support structured outputs, so this pattern is tied to a local or self-hosted server. Second, model capability still matters: a small model may satisfy a simple schema reliably and struggle with a large one, so schema complexity should be tuned to the model you run, and that tuning should be measured rather than assumed. Third, the documented examples use "stream": false. If your application depends on streaming, verify the behavior of your specific Ollama and library versions before designing around it, because the supplied documentation does not describe streaming semantics for schema-constrained requests.

Troubleshooting checklist

  1. Output is prose, not JSON. Confirm the format value is actually being sent — a schema placed only in the prompt is a suggestion, not a constraint. Also check that the client library is current, since older versions do not pass schemas through.
  2. Valid JSON with missing or unexpected keys. Compare the response against the schema you sent. If a key is absent, it was probably not listed in required. If an extra key appears, tighten the schema and restate the exact field list in the prompt.
  3. Pydantic validation errors. Print response.message.content before validating. A mismatch between the schema you sent and the Pydantic model — a renamed field, or a str where the schema declares an array — is the most common cause.
  4. The request fails or the model behaves oddly with a large schema. Reduce the schema to the fields you actually use, then add fields back one at a time to find the breaking point.
  5. Values are shaped correctly but wrong. This is a prompting problem, not a schema problem. Add the schema text and a short definition of each field to the user message, and give the model the source text in a clearly delimited block.

An illustrative workflow: structured extraction into WordPress

The following is a design sketch, not a tested deployment. It shows where schema-constrained output fits in an automation chain.

A local model reads a draft document and returns an object matching a schema such as {"title": string, "summary": string, "tags": array of string, "status": enum}. A script validates that object with Pydantic and then posts it to the WordPress REST API at /wp-json/wp/v2/posts, mapping title to the post title and tags to tag IDs. The schema guarantees the script never has to parse prose; the validation step guarantees a malformed response stops the pipeline instead of creating a broken post. Keep a human review step before publishing anything the model generated, because schema conformance says nothing about factual accuracy or editorial fit.

Where to go next

Start with a single-field schema against the model you already run, confirm the round trip end to end, and only then expand. If you hit a wall — a schema the model will not satisfy, a validation error you cannot place, or a version where format behaves differently — describe your operating system, Ollama version, model, the schema you sent, and the raw response in the community discussion, since those details are what make a problem reproducible for someone else.

FAQ

Does Ollama's cloud support structured outputs?

No. Ollama's documentation states that its cloud currently does not support structured outputs, so schema-constrained generation in this workflow runs against a local Ollama server.

Is JSON mode the same as passing a JSON schema?

No. Setting format to "json" asks for well-formed JSON without specifying keys. Passing a schema object constrains the output to the fields and types you define, which Ollama describes as more reliable and consistent than JSON mode.

Does a valid schema response mean the values are correct?

No. The schema constrains structure, not accuracy. A response can match the schema exactly and still contain a wrong or invented value, so factual review is still required for anything consequential.

Do I have to put the schema in the prompt as well as in format?

Ollama's documentation recommends it. The format field enforces the shape, while including the schema text in the prompt helps the model understand what each field is meant to contain.

Can I use Pydantic instead of writing the schema by hand?

Yes. Ollama's documentation recommends defining the structure as a Pydantic model and passing model_json_schema() to format, then validating the returned content against the same model.

References

  1. https://docs.ollama.com/capabilities/structured-outputs
  2. https://registry.ollama.ai/blog/structured-outputs

Related terms

JSON Schema
A declarative vocabulary for describing the structure of JSON data, including which keys exist, their types, and which are required. Ollama accepts a schema in the format field to constrain model output.
JSON mode
The looser option in Ollama, enabled with format: "json". It asks the model to emit JSON without dictating which keys appear, so the shape is not guaranteed.
format parameter
The chat API field that carries either the string "json" or a full JSON schema object to the model.
model_json_schema()
A Pydantic method that serializes a model class into a JSON Schema, which Ollama's documentation recommends passing to the format field.
model_validate_json()
The Pydantic v2 call that parses a JSON string into a typed model instance and raises an error if the payload does not conform.

Leave a Reply

Your email address will not be published. Required fields are marked *