Structured Outputs
Intermediate 12 min read Structured Outputs

JSON Mode & Enforcement

What the platform guarantees

Platform JSON modes constrain the model: guaranteed parseable JSON, some with schema enforcement. Knowing which guarantee your platform gives (well-formed-only vs schema-valid) decides your validation burden.

json modeenforcementresponse formatguaranteeparse
Prerequisites: JSON Schemas
Before we start

What you will learn

  • Enable JSON mode correctly
  • Know the platform's guarantee level
  • Design the fallback for unenforced schemas
Introduction

What is this?

'JSON mode' varies by provider: some guarantee only well-formed JSON syntax, others guarantee schema-valid JSON via structured decoding. Before relying on it, read the guarantee: syntax-only modes still need schema validation plus a repair path; schema-typed modes still need a sanity check.

Motivation

Why do you need it?

  • Syntax ≠ schema: well-formed JSON can still be the wrong shape.
  • Wasted hours come from expecting a guarantee the platform doesn't make.
  • Repair loops cost tokens; knowing the guarantee budgets them.
  • Every mode's defaults (temperature, prompts) differ — behavior follows.
Think about it

Mental model

Imagine

'A parking space' vs 'a disabled-bay space'

Think of

JSON mode guarantees

Syntax-mode guarantees just that your car won't be on the road — you may still be in a loading zone. Schema-mode parks you in the exact allotted bay. Same word 'space', different guarantee — read the fine print.

Mechanics

How it works

  • Check the provider's docs: does the mode constrain tokens to JSON syntax? To the schema?
  • If schema-constrained, pass the schema and trust the parse (still validate).
  • If syntax-only, add prompt instruction + validator + repair loop.
  • Note interactions: JSON modes may conflict with certain params (e.g. temperature forced).
  • Log mode + provider + validation results into traces.

Guarantee ladder.

Free text
JSON syntax
Schema valid
Your validation
Real world

In production

  • Chat-to-JSON apps enable syntax mode and add a schema repair loop.
  • High-stakes endpoints use schema-constrained structured output.
  • Mixers: schema mode for the core fields plus a free text slot.
Guidelines

Best practices

  • Read the guarantee, not the marketing.
  • Always validate the result yourself.
  • Design the repair path before the first parse failure.
  • Pin provider version; mode semantics change between releases.
Watch out

Common mistakes

  • Assuming syntax mode guarantees your shape.
  • No repair loop 'because the mode is guaranteed'.
  • Forgetting JSON mode forced temperature/casing quirks.
Root cause analysis

Common issues

Error
Mode produces prose anyway
Root cause

Provider mode off or malformed config

Fix

Check parameters, model version, and SDK option names.

Error
Schema mode rejects valid-ish data
Root cause

Enum too narrow or type mismatch

Fix

Inspect actual outputs; widen enums/relax types via repair.

When things break

Debugging tips

  • Valid JSON, wrong fields → mode is syntax-only; add schema validation.
  • Mode 'works' in demo, not prod → params/temperature overrides; replicate.
  • Schema edge values missing → schema too strict for real model outputs.
Interviews

Interview checkpoint

Test yourself

Quick quiz

0/2
1

Syntax-only JSON mode guarantees…

2

You should still validate schema-constrained mode outputs.

Go deeper

Official documentation

JSON mode (OpenAI)
docs