Glossary
JSON mode
JSON mode is a setting forcing a model's reply into a plain-text format software can read reliably, which guarantees the reply will parse and guarantees nothing about what is in it.
In plain terms
A promise about the envelope, not the letter. Switching it on means whatever comes back will be readable by software rather than being a paragraph with a stray sentence in front of it. What fields are inside, what they are called and whether the values are right are all separate questions the setting does not touch.
Why it matters
It solves a genuinely annoying problem and gets mistaken for solving a larger one. Before it existed, a step expecting machine-readable output would break whenever a model added a friendly preamble, and a great deal of fragile code existed purely to strip those. Switching it on removes that class of breakage entirely. What it does not do is make the reply the shape you wanted, which is the thing it is natural to assume you have just bought.
How it works
The provider constrains what the model may produce so the result is guaranteed to parse. That is a real technical guarantee rather than an instruction, which is why it works where asking the model nicely for the same thing did not.
It says nothing about which fields appear. A reply can be perfectly valid and contain field names your next step has never heard of, or omit one it was relying on. Where a provider also supports enforcing a described shape, that is the setting that answers the question people think this one answers.
Most providers require you to mention the format in the request as well, and a model told to produce this format with no description of what to put in it will invent a reasonable structure of its own. Reasonable and what you were expecting are not the same thing, which is the usual way this disappoints.
It has no bearing on whether the values are correct. A well-formed reply with an invented figure in it is the ordinary case rather than an unusual one, and the neat formatting will make it read to you as more reliable than the same claim in a sentence would.
A reply that parses perfectly and is useless
Seen in the wild
Switch it on for a step that kept breaking on a friendly preamble, which is the specific problem it removes.
n8nAsk for machine-readable output twice, once by request and once with the setting enabled, and see which one occasionally arrives with a sentence in front of it.
OpenRouterSend the same request with no description of the fields you want and read what structure comes back, which will be reasonable and not yours.
ChatGPT
Common misconceptions
People assume
It makes the output the right shape.
In fact
It makes the output parseable. Which fields exist and what they are called is a separate matter, answered by describing the shape you want and, where the provider supports it, having that description enforced. Treating this setting as shape control is the characteristic disappointment here.
People assume
Valid output means correct output.
In fact
The two are unconnected, and the formatting makes the error harder to notice. A tidy reply with a fabricated value passes every check a machine can perform on it, which is precisely why the checks that matter have to look at the values rather than the structure.
Telling them apart
JSON mode vs Structured output
JSON mode
A guarantee about the format: the reply will parse. Narrow, reliable, and silent on content.
A description of the fields you want, and where supported, enforcement of it before the reply reaches you.
Switch this on and describe the shape as well. On its own it removes a breakage and leaves the question you actually had.
Questions
- Should we just always switch it on?
- For anything a machine reads, yes, since it costs nothing and removes a class of breakage. Just do not stop there. Describe the fields you want in the request, and where the provider offers enforcement of that description, use it, because that is what answers the shape question.
- Why did we get valid output with the wrong field names?
- Because nothing told the model which names to use. Left to itself it produced a sensible structure, which is not yours. Describing each field, with the name you want and a short explanation of what belongs in it, fixes this and takes a few minutes.
- What should we check, given it guarantees only the format?
- Point your checks at the values rather than the structure, because the structure is now the one thing that cannot be wrong. Compare a sample of extracted figures against the source documents they came from, and treat a field that arrived empty as a result worth reading rather than a record to skip.
Key takeaways
- It guarantees the reply will parse, and guarantees nothing about the fields or the values.
- It is a real technical constraint rather than an instruction, which is why it works reliably.
- Without a description of the fields you want, the model invents a reasonable structure of its own.
- Neat formatting makes an invented value read as more trustworthy than the same claim in a sentence.
- Switch it on and describe the shape as well; on its own it answers the smaller half of the problem.
Tools that use this
- n8n
The step that kept breaking on a preamble, and stops.
- OpenRouter
Requested against enforced, where the difference shows occasionally.
- ChatGPT
No field description, so the structure that comes back is the model's.
Last checked July 2026