Getting an LLM to return reliable JSON is two problems, not one: your prompt has to satisfy the provider’s JSON-mode requirements, and the output has to match the shape your code expects. This tool checks both — without sending anything anywhere.
How it works
OpenAI’s response_format: { type: "json_object" } mode has a quiet requirement: the word JSON
must appear somewhere in the conversation, or the API returns an error. The first check scans your
system prompt for an explicit JSON instruction and, if it is missing, gives you a ready-to-paste
rewrite that appends a clear “respond with a single valid JSON object only” line.
The second check parses your sample response and walks it against your schema sketch. The schema is
just JSON where the structure is matched recursively and each leaf is a type name — "string",
"number", "boolean", "null". Missing required keys and type mismatches are reported with their
full path (for example address.zip: expected string, got number) so you know exactly what to fix.
JSON mode vs. Structured Outputs — the key difference
| Feature | JSON mode (json_object) | Structured Outputs (json_schema, strict) |
|---|---|---|
| Guarantees syntactically valid JSON | Yes | Yes |
| Guarantees schema compliance | No | Yes |
| Requires “JSON” in prompt | Yes | No |
| Supported on | Most OpenAI/compatible models | Specific models only |
| Runtime validation needed | Yes, in your code | No |
When to use JSON mode: You need valid JSON output but your schema is simple, you are on a model that does not support structured outputs, or you want to keep the prompt flexible and validate in application code.
When to use Structured Outputs: You have a precise schema, you are on a supported model (GPT-4o and newer with strict: true), and you want the API to enforce shape guarantees rather than relying on prompt engineering.
This tool helps with both paths: it checks the prompt for JSON mode compliance, and its schema validator simulates the shape check you would do in application code — or that the API performs automatically in structured-output mode.
Writing a good JSON-mode system prompt
A minimal system prompt that satisfies the JSON-mode requirement:
You are a data extraction assistant. Always respond with a single valid JSON object only — no prose, no markdown, no code fences. The response must contain these keys: name (string), date (string in YYYY-MM-DD format), and amount (number).Key elements: an explicit statement that the output should be JSON, no extra formatting (code fences confuse some parsers), and a list of expected keys with their types. The more specific the instruction, the less likely the model is to drift — especially at lower temperatures.
Common JSON parsing failures and causes
Trailing commas — {"a": 1,} is invalid JSON even though JavaScript allows it. Models trained heavily on JavaScript code occasionally produce trailing commas. Remove them before parsing.
Single quotes — {'key': 'value'} is Python dict notation, not JSON. Models mixing Python examples into training data sometimes use single quotes. Replace all string delimiters with double quotes.
Markdown code fences — A response wrapped in ```json ... ``` is not parseable JSON. Strip the fence before calling JSON.parse. The prompt should explicitly say “no code fences.”
Comments — // this is a comment is not valid JSON. Some models add explanatory comments inline. A JSON parser will reject these; strip them or instruct the model not to add them.
Truncated output — If max_tokens cuts the response mid-object, you will have unparseable JSON. Either increase max_tokens or design the schema to be small enough that a typical response completes well within the limit.
When to use which mode
Plain JSON mode only guarantees syntactic validity — you still have to validate the shape yourself,
which is what the schema check here mirrors. If your provider supports Structured Outputs
(json_schema with strict: true), the shape is guaranteed by the API and you can trust the keys and
types without runtime validation. Use this tool to design and sanity-check the schema before you wire
it into either path.
Tips
- Keep the schema minimal — only the keys your code actually reads. Extra keys in the response are fine and are ignored by the validator.
- For arrays, supply a single example element; every item in the response is validated against it.
- If you are on a model without native structured outputs, keep the validation in your own code too — JSON mode can still return an empty object or omit optional keys.