Structured output and tools

Get predictable JSON from a supported model. Check the formats available for your endpoint in /v1/catalog/models, then send an output schema.

Choose an output format

JSON mode returns a JSON object. JSON Schema also constrains its fields and values. Choose your API below and replace my-model with a model that advertises json_schema for that endpoint.

POST/v1/chat/completions

import os

from openai import OpenAI

client = OpenAI(
    base_url="https://api.boardwalk.cloud/v1",
    api_key=os.environ["BOARDWALK_API_KEY"],
)

response = client.chat.completions.create(
    model="my-model",
    messages=[
        {
            "role": "user",
            "content": "Return status \"ok\" and a null note as JSON."
        }
    ],
    max_completion_tokens=1024,
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "result",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "status": {"type": "string", "enum": ["ok", "needs_review"]},
                    "note": {"type": ["string", "null"]}
                },
                "required": ["status", "note"],
                "additionalProperties": False
            }
        }
    },
)
print(response.choices[0].message.content)
print(response.usage)

SDK setup: pip install openai · npm install openai. cURL needs no SDK.

For JSON mode, use {type: "json_object"} in OpenAI Chat Completions response_format or OpenAI Responses text.format. Ask for JSON in the prompt. Anthropic Messages supports schema output only, on eligible vLLM deployments.

Supported schemas

Use an object root, declare required fields, and set additionalProperties: false for predictable objects. Arrays need an items schema. Nullable values and local, nonrecursive references are supported.

Schema keywords and limits

Supported keywords: type, properties, required, boolean additionalProperties, items, minItems, maxItems, scalar enum and const, anyOf, $defs, definitions, local $ref, title, and description. Nullable type arrays are accepted.

64 KiB; ten schema levels; 512 nodes after reference expansion.
256 properties and 256 enum values across the expanded schema.
Sixteen unions; eight branches per anyOf; array bounds up to 1024.

References must resolve inside $defs or definitions. Recursive and external references are rejected. Reference siblings allow only title and description. Omit $schema or use http://json-schema.org/draft-07/schema#.

Regex patterns, string and numeric constraints, conditional schemas, allOf, and oneOf are unsupported. Invalid or unsupported schemas return 400 before inference.

Function tools

Your application executes tools. Validate each call's arguments, then return its result with the original ID. Tool calling, strict arguments, parallel calls, and output schemas are separate capabilities; check tool_calling before using a control.

Those fields describe Chat controls. See the native restrictions for Responses and Messages. The output-schema subset above does not apply to function parameter schemas.

Reasoning controls

Reasoning output does not imply effort controls. If the model advertises reasoning_controls.thinking_toggle, disable thinking with:

Chat: reasoning_effort: "none"
Responses: reasoning: {effort: "none"}
Messages: thinking: {type: "disabled"}

Other effort levels and token budgets are unsupported. Chat also accepts chat_template_kwargs: {enable_thinking: true|false} on those models.

Streaming and incomplete output

Let your SDK assemble the stream, check its final status, then parse and validate the JSON. Token limits or disconnects can leave partial output. Schema compliance does not guarantee factual accuracy.

Wire formats follow the OpenAI and Anthropic contracts. Boardwalk's model availability, schema subset, and limits are the ones documented here.