JSON mode + JSON Schema

Structured Outputs

Structured outputs let supported chat models return machine-readable JSON through the response_format request field. Capability support varies by model. Applications should always validate model output before using it, even when using json_schema.

Structured-output flow

Step 1

Format requested

Step 2

Generation

Step 3

JSON text returned

Step 4

Parse & Validate

Step 5

Use in application

Modes

JSON Object

type: "json_object"

Requests JSON-formatted output, but does not enforce an application-defined schema.

Requirement: The prompt should clearly ask for JSON when required by the selected model.

Limitation: The result must still be parsed and validated for structural correctness.

JSON Schema

type: "json_schema"

Provides an explicit JSON Schema to constrain output toward the requested structure.

Note: Schema adherence and strictness depend heavily on the selected model and gateway implementation.

Limitation: The application must still validate the final data.

JSON Object

The simplest way to get JSON output. The model returns a valid JSON object, but the application does not explicitly control the shape via schema.

import os
import json
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DEVUP_API_KEY"],
    base_url="https://api.devupai.com/v1",
)

response = client.chat.completions.create(
    model="deepseek-ai/DeepSeek-V4-Pro",
    messages=[
        {
            "role": "user",
            "content": "Provide a JSON list of 3 scientific breakthroughs."
        }
    ],
    response_format={"type": "json_object"}
)

# Safely parse the JSON text
content = response.choices[0].message.content
parsed = json.loads(content)
print(parsed)

Illustrative response

json

{
  "breakthroughs": [
    {
      "name": "CRISPR-Cas9",
      "countries": ["USA", "France"],
      "year": 2012
    }
  ]
}

JSON Schema

JSON Schema requests output that follows the provided schema when supported by the selected model. Provide a valid JSON schema containing type, properties, required, and optionally additionalProperties.

"response_format": {

"type": "json_schema",
"json_schema": {

"name": "breakthrough",
"strict": true,
"schema": { ... }

}

import os
import json
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DEVUP_API_KEY"],
    base_url="https://api.devupai.com/v1",
)

response = client.chat.completions.create(
    model="deepseek-ai/DeepSeek-V4-Pro",
    messages=[
        {
            "role": "user",
            "content": "Extract the name, country, and year from: 'Alexander Fleming discovered Penicillin in the UK in 1928.'"
        }
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "breakthrough",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "country": {"type": "string"},
                    "year": {"type": "integer"}
                },
                "required": ["name", "country", "year"],
                "additionalProperties": False
            }
        }
    }
)

content = response.choices[0].message.content
print(json.loads(content))

Illustrative response

json

{
  "name": "Penicillin",
  "country": "UK",
  "year": 1928
}

Truncation and errors

Incomplete Output

Output may be incomplete if the request reaches its output-token limit. JSON parsing will fail on incomplete output. Do not silently trust partially generated JSON.

Finish Reason

Always inspect the response finish_reason. If it indicates length truncation, retry the request with a higher limit or simplify the schema.

Caveats

Application-side validation is required

Structured output reduces formatting uncertainty but does not replace application-side validation, error handling, or model-capability checks. Handle refusal, truncation, malformed output, and missing fields appropriately.

Best Practices

Model selection: Select a model that explicitly supports the required structured-output mode.

Schema complexity: Keep schemas small and explicit. Mark required fields clearly. Use additionalProperties: false only when appropriate.

Parsing: Always parse and validate the returned JSON text in your application code before using the data.

Context window: Ensure the output-token limit can easily accommodate the expected size of the returned object.

What's Next

Tool CallingConnect models to external functions.

Vision & OCRProcess and understand images.

Chat CompletionsOpenAI-compatible text generation.

ModelsBrowse the model catalog.