# 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](https://developers.openai.com/api/docs/guides/structured-outputs#supported-schemas). 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`.

```json
{
  "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"`.

```json
{
  "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.

```json
{
  "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.

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

Arrays can also contain objects for more complex structures:

```json
{
  "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`.

```json
{
  "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.

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

:::info{title="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](/docs/best-practices-and-use-cases#guide-the-llm-with-descriptions) for guidance on writing effective descriptions.

:::

### Union types with `anyOf`

Use `anyOf` when a field can take one of several structured forms.

```json
{
  "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

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