Scrapeless Wiki

What Is a JSON Schema Response Format? – Definition and How It Works

Informational P3 what is a json schema response format

Learn how a JSON Schema constrains model output, what constrained decoding guarantees, and which schema choices improve accuracy.

A JSON Schema response format declares the exact shape a model's output must take, so a caller receives typed fields instead of prose to parse.

1. What It Looks Like

{
  "type": "object",
  "properties": {
    "title":    { "type": "string", "description": "Product name as displayed" },
    "price":    { "type": "number", "description": "Numeric price, no symbols" },
    "currency": { "type": "string", "enum": ["USD", "EUR", "GBP"] },
    "in_stock": { "type": "boolean" },
    "rating":   { "type": ["number", "null"], "minimum": 0, "maximum": 5 }
  },
  "required": ["title", "in_stock"],
  "additionalProperties": false
}

2. Two Enforcement Mechanisms

Constrained decoding — the schema restricts which tokens may be generated, so output is structurally valid by construction. The strongest guarantee available.

Post-generation validation — the model is asked for JSON and the result is validated, with a re-prompt on failure. Weaker, and works with any provider.

Constrained decoding guarantees the container. It says nothing about whether the contents are correct.

3. Descriptions Are Read

Field descriptions are not documentation for humans; the model reads them and they materially affect accuracy.

"Numeric price, no currency symbols, excluding shipping" produces better extraction than a bare number type. This is the cheapest available improvement to a schema.

4. Enums Eliminate a Class of Error

A closed set as an enum makes an invalid value impossible under constrained decoding, and immediately detectable under validation.

Currency, status, category, and any controlled vocabulary belong as enums rather than free strings.

5. Nullability Must Be Honest

A required field with no permitted null forces the model to invent a value when the source does not contain one. That is the schema causing fabrication.

Where absence is possible, permit null and instruct that it be used. An explicit null is information; an invented value is not.

6. Keep Schemas Flat and Focused

Deeply nested schemas and very large field counts both degrade accuracy. Splitting a large extraction into several calls with focused schemas usually produces better results than one call with an elaborate one.

additionalProperties: false is also worth setting, so unexpected fields are a failure rather than silent noise.

7. Validate Beyond the Schema

Structure is not truth. Layer checks:

  1. Schema validation for shape.
  2. Range and plausibility checks for values.
  3. Cross-field consistency.
  4. A bounded re-prompt path that includes the specific validation error, since a model can correct a fault it is told about.

8. Summary

A JSON Schema response format declares the output shape, enforced either by constrained decoding or by validation with a re-prompt.

Write real field descriptions, use enums for closed sets, permit null honestly so absence is not fabricated, keep schemas flat, and validate values as well as structure — because a guaranteed container can still hold a wrong number.