building structured json output with llm api

If you want structured JSON output from an LLM API, the safest pattern is:

1. Define the schema
2. Tell the model to output only JSON
3. Validate the response
4. Retry / repair if invalid

1) Use a schema

Example JSON structure:

{
  "name": "Alice",
  "age": 30,
  "skills": ["python", "sql"],
  "is_active": true
}

2) Prompt the model clearly

Good prompt:

Return only valid JSON matching this schema:

• name: string
• age: integer
• skills: array of strings
• is_active: boolean

Do not include markdown, commentary, or extra text.

3) Example API pattern

Python

import json

response = client.responses.create(
    model="gpt-4.1",
    input="Return only JSON with keys: name, age, skills, is_active."
)

text = response.output_text
data = json.loads(text)
print(data)

4) Better: use structured output / JSON schema if supported

Many modern LLM APIs support JSON mode or schema-constrained output.

Example idea:

schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string"},
        "age": {"type": "integer"},
        "skills": {
            "type": "array",
            "items": {"type": "string"}
        },
        "is_active": {"type": "boolean"}
    },
    "required": ["name", "age", "skills", "is_active"],
    "additionalProperties": False
}

Then send that schema to the API and ask it to comply.

5) Validate the result

Use a validator like:

• jsonschema in Python
• Zod in TypeScript
• Pydantic in Python

Example with Python jsonschema:

from jsonschema import validate

validate(instance=data, schema=schema)

6) Handle failures

LLMs sometimes return:

• trailing text
• malformed JSON
• wrong types
• missing fields

Common fix:

• try parsing
• if it fails, ask the model to repair the JSON
• reject anything that doesn’t validate

---

If you want, I can give you:

1. a Python example with OpenAI structured outputs,
2. a TypeScript example, or
3. a generic prompt template for any LLM API.