Extraction schema reference
Define dataExtractionSchema with JSON Schema to specify the information an Assistant extracts after a call. The API validates it when you save the Assistant.
Schema requirements
The extraction model uses OpenAI Structured Outputs. The Data API validates JSON Schema syntax and the constraints below on save. This check is not a complete implementation of the provider's schema restrictions: a schema can pass the save check and still fail during extraction.
Use an object at the root and follow OpenAI's supported schema subset. Root-level anyOf is not supported by the provider.
| Constraint | Requirement |
|---|---|
Schema node type | Every schema node must include a type or use a recognized schema composition or reference. Use $ref or nested anyOf for extraction schemas. |
additionalProperties | Must be set to false on every object. |
required | Must list all keys defined in properties. Every property must be required. |
properties | Required on every node with type: "object". |
items | Required on every node with type: "array". |
| Recursive validation | Nested objects and arrays are validated against the same constraints recursively. |
Supported features
The following patterns are suitable for extraction schemas. Examples that show only named fields are fragments to place inside a parent object's properties.
Basic types
The standard JSON Schema primitive types are supported: string, number, integer, and boolean.
Code
Nullable fields
To allow a field to be null when the LLM cannot extract a value from the conversation, use an array type with "null".
Code
Use nullable fields for information that may not be mentioned during a conversation. The field remains required in the schema, but its value can be null.
Enums
Constrain a string field to a fixed set of values using enum. The LLM will select the most appropriate value from the list.
Code
Arrays
Use type: "array" with an items definition to extract lists of values. The items schema can be any supported type.
Code
Arrays can also contain objects for more complex structures:
Code
Nested objects
Use nested objects to group related fields. Each nested object must include properties, required, and additionalProperties: false.
Code
Descriptions
Every property should include a description field. The LLM uses these descriptions to determine what information to extract and how to interpret ambiguous dialogue.
Code
Note
Descriptions are not enforced by the schema validator. Use them to explain what each field should contain and test the results on representative conversations. See Best practices & Use cases for guidance on writing effective descriptions.
Union types with anyOf
Use anyOf when a field can take one of several structured forms.
Code
Limitations
| Constraint | Detail |
|---|---|
additionalProperties | Must be false on every object node. Open-ended objects are not supported. |
| All properties required | Every key in properties must appear in the required array. Optional fields are not supported at the schema level; use nullable types instead. |
default values | Do not rely on defaults to fill missing information. Use nullable fields and explicit descriptions instead. |
| String validation keywords | Supported string constraints depend on the keyword and model. Unsupported constraints can cause extraction to fail; they are not guaranteed to be ignored. |
$ref references | Use references within the same schema document, such as #/$defs/item; do not use external files. |