JSON Mode

JSON mode is a generation setting that guarantees a model's entire output will be syntactically valid JSON — properly matched braces, quoted keys, valid escaping — without guaranteeing that JSON matches any particular schema, field names, or types.

It sits between two very different guarantees that are easy to conflate. Plain prompting ("please respond in JSON") gives you nothing enforced — the model usually complies, occasionally wraps the object in explanatory prose or a markdown code fence, and every so often produces a trailing comma that breaks a strict parser. JSON mode fixes the syntax layer: whatever the model produces will parse. It does not fix the schema layer: the model can still invent field names, omit fields you needed, or nest data differently than you expected, because nothing has told it what fields to use, only that the result must be valid JSON syntax.

How it works

Under the hood, JSON mode constrains decoding against the grammar of JSON syntax itself, not against any schema describing your specific object — the same kind of token-masking used in full structured outputs, just aimed at a much smaller target: valid braces, brackets, quotes, and commas, rather than a specific set of named fields with specific types. That narrower scope is precisely why it is cheaper and more universally supported than full schema-constrained structured outputs, and why it ships as a simpler flag on more providers.

The gap it leaves has to be closed somewhere. Most teams pair JSON mode with a clearly specified schema written into the prompt itself, plus code-level validation on the receiving end, accepting that the model might still deviate and building a defense for when it does.

Why it matters

JSON mode eliminates an entire, extremely common class of production bug — the parse error from a stray code fence or an unescaped quote — for close to zero engineering cost. It is the right tool when the output shape is simple and mostly stable, and full schema enforcement would be overkill. It is the wrong tool to rely on alone when field names, types, or enum values genuinely must be exact, because JSON mode has no opinion on any of that — only structured outputs, with an actual schema behind it, does.

A worked example

Prompt: "Summarize this review as JSON with a sentiment and a one-line summary." Without JSON mode, a plausible response opens with "Here's the JSON you asked for:" followed by the object wrapped in a markdown code fence — correct information wrapped in text and formatting that breaks a naive parse call. With JSON mode enabled, the output is exactly the object and nothing else — but note the model was free to name the field "summary" instead of "review_summary," or return a nested object instead of a flat one, because JSON mode never saw a schema to conform to, only a syntax to obey.

How Miatz teaches it

Learners in the structured-output labs build the same extraction task twice, once under JSON mode alone, once under full schema-constrained structured outputs, and diff the field-name and type drift between runs, making concrete exactly where JSON mode's guarantee ends and a schema's guarantee begins.