Output Contracts and JSON Mode

A practical guide to output contracts and json mode within the advanced prompt engineering skill.

What This Lesson Covers

Output Contracts and JSON Mode is a foundational technique in advanced prompt engineering. In this lesson you will learn what it is, why it matters in production, the mechanics behind it, and the patterns experienced practitioners use to avoid common pitfalls. By the end you will be able to apply output contracts and json mode in real systems with confidence.

This lesson belongs to the Prompting & LLM Mastery track. The skills in this track are deliberately the kind a working AI engineer reaches for week after week — not academic curiosities. Everything is grounded in patterns that ship in real production systems.

Why It Matters

Master the craft of prompt engineering: structured prompts, system messages, role design, output contracts, and reliable instruction-following at scale.

The reason output contracts and json mode deserves dedicated attention is that the difference between a beginner and an expert often comes down to the small decisions made here. Two engineers using the same model and the same data can produce wildly different results based on how well they execute on this skill alone. Understanding the underlying mechanics — not just memorizing recipes — is what lets you adapt when the stock approach does not work.

How It Works in Practice

Below is a worked example showing how to apply output contracts and json mode in real code. Read through it once, then experiment by changing the parameters and observing the effect.

from pydantic import BaseModel, Field
from openai import OpenAI

class Invoice(BaseModel):
    vendor: str
    total: float = Field(ge=0)
    line_items: list[str]

client = OpenAI()
result = client.chat.completions.parse(
    model="gpt-4o-2024-08-06",
    messages=[{"role": "user", "content": "Extract invoice fields"}],
    response_format=Invoice,
)
invoice: Invoice = result.choices[0].message.parsed

Step-by-Step Walkthrough

1. Set up the environment — Make sure you have the relevant SDK installed (openai, anthropic, transformers, etc.) and an API key or model artifact ready.
2. Define your inputs cleanly — Garbage in, garbage out. The vast majority of output contracts and json mode failures trace back to messy or ambiguous input that the practitioner did not catch.
3. Pick the right hyperparameters — The defaults are tuned for a generic case. Your case is rarely generic. Spend a few minutes thinking about which knobs matter most for your data.
4. Measure before and after — Without a metric you cannot tell if your change helped. Even a tiny eval set of 30 examples is dramatically better than no eval set at all.
5. Iterate fast — Make one change, measure, repeat. Resist the urge to change three things at once; you will not know which change moved the metric.

When To Use It (and When Not To)

Output Contracts and JSON Mode is the right tool when:

• You need a repeatable, measurable approach — not a one-off experiment
• The volume justifies the engineering effort to set it up properly
• You have a clear way to evaluate whether the technique improved your outcome
• The cost and latency budget can absorb whatever overhead it adds

It is the wrong tool when:

• A simpler approach already meets your quality bar
• You do not yet have any eval signal — build the eval first
• The added complexity will outlive your willingness to maintain it

Production Checklist

• Have you logged inputs and outputs so you can debug failures after the fact?
• Is there an eval set that exercises the edge cases this technique is supposed to handle?
• Have you set timeout, retry, and cost guardrails so a bad request cannot blow up your budget?
• Did you document why you chose this approach — so the next engineer (or future you) knows what to leave alone?
• Is the cost and latency overhead acceptable at your traffic volume, not just at the demo?

Next Steps

The other lessons in Advanced Prompt Engineering build directly on this one. Once you are comfortable with output contracts and json mode, the natural next step is to combine it with the techniques in the surrounding lessons — that is where the compound returns kick in. Skills are most useful as a system, not as isolated tricks.