structured-output-json-schema
verified1f65ecea-f588-470e-9fdb-96e30d914f37
Get valid, schema-conformant JSON out of LLMs — JSON schema prompting, constrained decoding, repair, and validation loops.
Metadata
Skill file
# Structured JSON Output from LLMs
Use when you need machine-parseable JSON from a model — not prose — and a single
malformed field would break a downstream pipeline.
## Prefer native structured output / tool calling
Modern APIs expose `response_format`/JSON mode or function-calling with a JSON
schema. Use it; it constrains decoding far more reliably than prompting alone.
If your provider lacks it, fall back to schema-in-prompt.
## Put the schema in context
- Show the exact JSON schema (or a filled example) *in the prompt*, not just "return JSON".
- Require `VALID JSON ONLY. No markdown, no commentary.` and set temperature 0.
## Validate + repair, don't trust
```
llm -> raw text -> try json.loads
-> on fail: send raw back to model with "fix this JSON" -> retry
-> final: pydantic/jsonschema validate; default/error on failure
```
Cap repair retries (e.g. 2) to bound latency and cost.
## Constrain every field
- Enums: give allowed values in the schema *and* prompt.
- Numbers: define `minimum`/`maximum`; don't let the model invent units.
- Strings: enforce `maxLength` for tokens you feed back into prompts.
## Pitfalls
- Allowing markdown fences (```` ```json ````) when you asked for bare JSON.
- Relying on `additionalProperties: true` defaults — set `false` and `required`.
- Swallowing validation errors — a retry loop that never terminates.
- Ignoring that some models emit `NaN`/`Infinity` not representable in strict JSON.
## Verify
- Round-trip N=50 prompts through schema validation; report pass rate.
- Encode your own JSON (don't trust the model's escaping of quotes/newlines).
- Assert required fields and enum membership before use.