Structured output

A JSON Schema describes the shape and limits of a JSON value. Structured output makes Unbar return JSON that matches a schema you supply.

Request JSON that matches your schema

Send a response_format object with type: "json_schema" and your schema. The same rules apply to the arguments of a tool call or a function call. Unbar checks every response against your full schema. Unbar returns the answer only after it matches your schema.

Constraints that Unbar enforces

Unbar rejects a response that breaks one of these constraints:

• Structure: type, required, enum, additionalProperties.
• String length: minLength, maxLength.
• Number range: minimum, maximum, multipleOf.
• Array size: minItems, maxItems, uniqueItems.
• Object size: minProperties, maxProperties.
• Composition: $ref and $defs, allOf, and nested objects declared through them.

Constraints that you check yourself

Unbar does not enforce two keywords. Unbar passes them through unchecked. Check them yourself when you need them.

• pattern — a regular expression. Unbar does not run it, because a regular expression can be unsafe to evaluate on arbitrary input.
• format — a named format such as email or date-time. A format check is ambiguous. It can reject a value that your own validator accepts.

When a response cannot match your schema

By default, Unbar returns a 422 response when a response cannot match your schema. The error.type is invalid_request_error. The error.code is structured_output_unsatisfiable. The message names the field, the constraint keyword, and the limit that failed.

Unbar checks the response against your schema and tries again internally before it returns this error.

To resolve a 422, relax the constraint that failed, or choose a different model.

Choose how strict Unbar is

Send the X-Structured-Output-Strictness header to choose what happens when a response cannot match your schema. The default is strict. With strict, you get the 422 above. Set the header to lenient to receive the best-effort answer as a normal 200 response. Then check the answer yourself.

The value is case-insensitive. An absent, empty, or unrecognized value uses the safe default strict. Unbar never rejects an unrecognized value as a bad request.

Example

This example sends a small schema with a maxLength limit. It shows how to send the strictness header and what the 422 response contains.

import os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ["UNBAR_BASE_URL"],
    api_key=os.environ["UNBAR_API_KEY"],
)
model = os.environ["UNBAR_MODEL"]

schema = {
    "type": "object",
    "properties": {
        "rationale": {"type": "string", "maxLength": 600},
    },
    "required": ["rationale"],
    "additionalProperties": False,
}

response = client.chat.completions.create(
    model=model,
    messages=[{"role": "user", "content": "Give a short rationale for using a cache."}],
    response_format={
        "type": "json_schema",
        "json_schema": {"name": "answer", "schema": schema},
    },
)
print(response.choices[0].message.content)

To receive the best-effort answer instead of a 422, add the strictness header. The OpenAI client sends it through extra_headers.

response = client.chat.completions.create(
    model=model,
    messages=[{"role": "user", "content": "Give a short rationale for using a cache."}],
    response_format={
        "type": "json_schema",
        "json_schema": {"name": "answer", "schema": schema},
    },
    extra_headers={"X-Structured-Output-Strictness": "lenient"},
)

When the answer cannot match the schema and the header is strict, Unbar returns this body:

{
  "error": {
    "type": "invalid_request_error",
    "message": "The response did not satisfy the schema constraint on rationale (maxLength 600). Relax this constraint, or set \"X-Structured-Output-Strictness: lenient\" to receive the answer anyway.",
    "param": null,
    "code": "structured_output_unsatisfiable"
  }
}

Report a problem

Email support@unbar.sh with the model, request identifier, and a description of the problem. Do not send API keys. Do not send private prompts.

How to verify your requests · Published model rates · Privacy Policy