Reecall
Data Extraction

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.

ConstraintRequirement
Schema node typeEvery schema node must include a type or use a recognized schema composition or reference. Use $ref or nested anyOf for extraction schemas.
additionalPropertiesMust be set to false on every object.
requiredMust list all keys defined in properties. Every property must be required.
propertiesRequired on every node with type: "object".
itemsRequired on every node with type: "array".
Recursive validationNested 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.

JSONCode
{ "type": "object", "properties": { "motive": { "type": "string" }, "callCount": { "type": "integer" }, "satisfactionScore": { "type": "number" }, "issueResolved": { "type": "boolean" } }, "required": ["motive", "callCount", "satisfactionScore", "issueResolved"], "additionalProperties": false }

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".

JSONCode
{ "product": { "type": ["string", "null"], "description": "The product or service discussed, or null if not mentioned." } }

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.

JSONCode
{ "motive": { "type": "string", "description": "The main reason why the user is calling.", "enum": ["Technical Support", "Billing", "Appointment request", "General enquiry"] } }

Arrays

Use type: "array" with an items definition to extract lists of values. The items schema can be any supported type.

JSONCode
{ "topicsDiscussed": { "type": "array", "description": "List of distinct topics raised during the conversation.", "items": { "type": "string" } } }

Arrays can also contain objects for more complex structures:

JSONCode
{ "actionItems": { "type": "array", "description": "Follow-up actions identified during the conversation.", "items": { "type": "object", "properties": { "action": { "type": "string", "description": "Description of the action to take." }, "assignee": { "type": ["string", "null"], "description": "Who is responsible, or null if unassigned." } }, "required": ["action", "assignee"], "additionalProperties": false } } }

Nested objects

Use nested objects to group related fields. Each nested object must include properties, required, and additionalProperties: false.

JSONCode
{ "type": "object", "properties": { "motive": { "type": "string" }, "resolution": { "type": "object", "description": "Details about how the issue was resolved.", "properties": { "resolved": { "type": "boolean", "description": "Whether the issue was resolved." }, "method": { "type": ["string", "null"], "description": "How the issue was resolved, or null if unresolved." } }, "required": ["resolved", "method"], "additionalProperties": false } }, "required": ["motive", "resolution"], "additionalProperties": false }

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.

JSONCode
{ "urgency": { "type": "string", "description": "How urgent the caller's request is, based on the tone and content of the conversation.", "enum": ["low", "medium", "high"] } }

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.

JSONCode
{ "outcome": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": ["resolved"] }, "solution": { "type": "string", "description": "How the issue was resolved." } }, "required": ["status", "solution"], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "enum": ["escalated"] }, "department": { "type": "string", "description": "The department the issue was escalated to." } }, "required": ["status", "department"], "additionalProperties": false } ] } }

Limitations

ConstraintDetail
additionalPropertiesMust be false on every object node. Open-ended objects are not supported.
All properties requiredEvery key in properties must appear in the required array. Optional fields are not supported at the schema level; use nullable types instead.
default valuesDo not rely on defaults to fill missing information. Use nullable fields and explicit descriptions instead.
String validation keywordsSupported string constraints depend on the keyword and model. Unsupported constraints can cause extraction to fail; they are not guaranteed to be ignored.
$ref referencesUse references within the same schema document, such as #/$defs/item; do not use external files.
Last modified on