Updated
Generate the schema
- Pick a sample that has every field filled in. A generator can not describe a field it never sees.
- Paste the sample into the generator and run it.
- Copy the schema into your project.
What you get
This sample:
{ "id": 1, "name": "Ada", "tags": ["new"] }The generated schema
Each field has a type. Each field is required. Fields the schema does not name are turned away. That strict shape is what AI models need for structured outputs.
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "GeneratedSchema",
"type": "object",
"properties": {
"id": { "type": "integer" },
"name": { "type": "string" },
"tags": { "type": "array", "items": { "type": "string" } }
},
"required": ["id", "name", "tags"],
"additionalProperties": false
}Six things to fix by hand
- Required fields. The generator marks all of them as required. To check API data, take the optional ones off the list. For OpenAI Structured Outputs, leave the list as it is. Every field must be required there.
- Fields that can be null. If a value can be null, change its type to a list such as ["string", "null"].
- Arrays. The generator reads only the first item. Check that the other items have the same shape.
- Fixed values. A field such as status has a short list of valid values. Swap the string type for an enum, a fixed list.
- Limits and formats. Where the data has rules, add minimum, maximum, minLength or a format such as email or date-time.
- Descriptions. Add a description to each field. An AI model reads them as instructions. So does the next developer.
Test the schema
Make sample data from the finished schema and read it. Does a record look wrong, like a price below zero or an empty list? Then the schema allows too much.
Next, run a real file through a validator, such as Ajv in JavaScript or jsonschema in Python.
Using the schema with an LLM
OpenAI, Anthropic and Google all take a JSON Schema to set the shape of a model's answer. Each one supports only some of the keywords. Types, properties, required, enum and descriptions work everywhere. Check the docs before you count on limits such as minimum or pattern.