Official documentation for supported schemas for `response_format` parameter in calls to `client.beta.chats.completions.parse`

Documentation
1

I am trying to enforce a JSON schema as an output of an LLM. I found this post and have been trying to use my JSON schema. Is there no support to oneOf, anyOf, or any similar features of JSON schemas? Where can I find where all the documentation for this kind of expected formats is? I also tried using pydantic and BaseModel’s to replicate my JSON schema but ran into similar issues with more complex logic involving different combinations of requirements. I have basically been trying to use something like this:

my_schema = {    
    "type": "json_schema",
    "json_schema": {
        "name": "example_schema",
        "strict": True,
        "schema": {
            "type": "object",
            "properties": {
                "A": {
                    "type": "string"
                },
                "B": {
                    "type": "number"
                },
                "C": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                }
            },
            "oneOf": [
                {
                    "required": ["A"]
                },
                {
                    "required": ["B"]
                },
                {
                    "required": ["C"]
                }
            ],
            "additionalProperties": False
        }
    }
}

completion = client.beta.chat.completions.parse(
    model="gpt-4o-2024-08-06",
    messages=messages, # this has a system prompt and user message
    response_format=my_schema
)

Running this gives me the error:

BadRequestError: Error code: 400 - {'error': {'message': "Invalid schema for response_format 'example': In context=(), 'oneOf' is not permitted.", 'type': 'invalid_request_error', 'param': 'response_format', 'code': None}}

Where can I find documentation for what formats are supported and what features are allowed? Also, is there a workaround for not being allowed to use oneOf and anyOf?

3 Likes
2

Did you solve it? I’m having the same issue

3

Your option is anyOf, to specify sub-schema, but it cannot be the root.

I can have an AI do a mind dump vs the documentation, and we can start to check off per data type keywords as yes or no – probably no if a more basic keyword specifically doesn’t work.

Current state of info below: just a few checked and noted.
(If supported) are speculative. I’ll update if you have feedback, but these kind of documentation threads quickly become bumped off and lost in the forum.

Based on the documentation and the list of unsupported keywords, here are the common and useful JSON Schema keywords that apply to each data type, which are not mentioned as unsupported and are commonly seen in JSON Schema:

String

  • type: Specifies that the data should be a string.
  • enum: Restricts the value to a fixed set of string values.
  • const: Requires the string to be exactly equal to a specified value.
  • contentEncoding: (If supported) Specifies the content encoding (e.g., base64).
  • contentMediaType: (If supported) Specifies the media type of the string contents (e.g., text/html).

Note: The keywords minLength, maxLength, pattern, and format are explicitly unsupported.

Number and Integer

  • type: Specifies that the data should be a number or integer.
  • enum: Restricts the value to a fixed set of numerical values.
  • const: Requires the number to be exactly equal to a specified value.
  • exclusiveMinimum: Requires the number to be greater than a specified value.
  • exclusiveMaximum: Requires the number to be less than a specified value.

Note: The keywords minimum, maximum, and multipleOf are explicitly unsupported.

Boolean

  • type: Specifies that the data should be a boolean.
  • enum: Can restrict the value to true or false.
  • const: Requires the value to be exactly true or false.

Object

  • type: Specifies that the data should be an object.
  • properties: Defines the properties and their respective schemas.
  • required: Lists the properties that must be present in the object.
  • additionalProperties: Controls whether properties not listed in properties are allowed.
  • dependencies: (If supported) Specifies property dependencies within the object.
  • patternDependentSchemas: (If supported) Applies schemas based on property patterns.

Note: The keywords patternProperties, unevaluatedProperties, propertyNames, minProperties, and maxProperties are explicitly unsupported.

Array

  • type: Specifies that the data should be an array.
  • items: Defines the schema for items within the array.
  • additionalItems: Controls whether additional items are allowed beyond those specified in items.
  • prefixItems: (If supported) Defines schemas for tuple validation.

Note: The keywords unevaluatedItems, contains, minContains, maxContains, minItems, maxItems, and uniqueItems are explicitly unsupported.

General Keywords Applicable to Multiple Data Types

  • enum: Restricts the value to a fixed set of values.
  • const: Requires the value to be exactly equal to a specified value.
  • anyOf: Requires the data to match at least one of the specified schemas.
  • allOf: (If supported) Requires the data to match all of the specified schemas.
  • oneOf: (If supported) Requires the data to match exactly one of the specified schemas.
  • not: (If supported) Requires the data to not match the specified schema.
  • if, then, else: (If supported) Conditional subschemas based on the data.
  • description: Provides a description for documentation purposes.
  • title: Provides a short title for the schema or property.
  • default: Specifies a default value for the data.

Additional Notes

  • Schema References only internal, obviously, but yes:

    • $ref: (no) References a schema defined elsewhere, allowing for schema reuse.
    • $defs or definitions: (yes) Allows for defining reusable schemas within the current schema.

  • Combining Schemas only allOf is even mentioned in dox:

    • allOf, oneOf, not: Useful for composing complex schemas from simpler ones. Since they are not listed as unsupported, they might still be supported.

  • Conditional Subschemas unknown, unlikely:

    • if, then, else: Enable conditional validation based on the value of the data.

  • Annotations unknown:

    • description and title: Useful for providing human-readable information about the schema, which can be important for documentation and tooling.
2 Likes
4

Hi @diego.delarue and welcome to the community!

Also relevant for @admin215 !

anyOf is supported and an example of its use is available here.

oneOf is currently not supported! So you would need to use anyOf in its place.

One caveat with anyOf is that it must not share identical first keys, which is a bit annoying.

4 Likes