> ## Documentation Index
> Fetch the complete documentation index at: https://docs.extend.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Processor output types

> Understanding different output types for document processors.

Document processor outputs follow standardized formats based on the processor type.
Understanding these formats is essential when working with evaluation sets, webhooks, and API responses.

## Extraction output type (JSON Schema)

<Note>
  This section is relevant for processors using the JSON Schema config type. If
  you are using the Fields Array config type, please see the [Extraction output
  type (Fields Array)](#extraction-output-type-fields-array) documentation. If
  you aren't sure which config type you are using, please see the [Migrating to
  JSON Schema](/product-reference/studio/migrating_to_json_schema)
  documentation.
</Note>

The output structure for JSON Schema processors is composed of two properties: `value` and `metadata`.

The `value` object is the actual data extracted from the document which conforms to the JSON Schema defined in the processor config.

The `metadata` object holds details like confidence scores and citations for the extracted data. It uses keys that represent the path to the corresponding data within the value object. Crucially, the keys in the `metadata` object mirror the structure of the `value` object using a path-like notation (e.g., `line_items[0].description`), allowing you to precisely pinpoint metadata for any specific field, including those nested within objects or arrays. For instance, if your data has value.line\_items\[0].name, the metadata specifically for that name field will be found using the key 'line\_items\[0].name' within the metadata object.

### Type definition

<CodeGroup>
  ```typescript TypeScript Types theme={null}
  type ExtractionOutput = {
    value: ExtractionValue;
    metadata: ExtractionMetadata;
  };

  type ExtractionValue = Record<string, any>; // Conforms to the schema defined in the processor config
  type ExtractionMetadata = {
    [key: string]: ExtractionMetadataEntry | undefined;
  };

  type ExtractionMetadataEntry {
    ocrConfidence?: number | null;
    logprobsConfidence: number | null;
    citations?: Citation[];
    insights?: OutputInsight[];
  }

  type Citation = {
    page?: number;
    referenceText?: string | null;
    polygon?: Point[];
  };

  type Point = {
    x: number;
    y: number;
  };

  type OutputInsight = {
    type: "reasoning";
    content: string;
  };
  ```
</CodeGroup>

### Accessing Metadata

To access the metadata for a specific field, especially nested ones like items in an array, you use a path-like key string. For example, to get the metadata for the `description` of the first item in a `line_items` array, the key would be `line_items[0].description`.

Here are examples in Python and TypeScript:

<CodeGroup>
  ```typescript TypeScript Example theme={null}
  const output = {
    value: {
      invoice_number: "INV-123",
      line_items: [
        { description: "Item A", quantity: 2, price: 10.0 },
        { description: "Item B", quantity: 1, price: 25.5 },
      ],
    },
    metadata: {
      invoice_number: {
        logprobsConfidence: 1,
        ocrConfidence: 0.99,
        citations: [
          {
            referenceText: "Invoice #: INV-123",
            page: 1,
            polygon: [
              { x: 296.73359999999997, y: 40.888799999999996 },
              { x: 386.4168, y: 40.464000000000006 },
              { x: 386.4744, y: 52.1712 },
              { x: 296.7912, y: 52.596000000000004 },
            ],
          },
        ],
      },
      line_items: {
        logprobsConfidence: 0.98,
        ocrConfidence: 0.98,
      },
      "line_items[0]": {
        logprobsConfidence: 0.98,
        ocrConfidence: 0.98,
        citations: [{ page: 1 }],
      },
      "line_items[0].description": { logprobsConfidence: 1, ocrConfidence: 0.95 },
      "line_items[0].quantity": { logprobsConfidence: 1, ocrConfidence: 0.98 },
      "line_items[0].price": { logprobsConfidence: 1, ocrConfidence: 0.98 },
      "line_items[1].description": { logprobsConfidence: 1, ocrConfidence: 0.96 },
      // Other metadata entries...
    },
  };

  // Traversing the output object and accessing metadata
  const invoiceNumber = output.value.invoice_number;
  const invoiceNumberMetadata = output.metadata.invoice_number;

  // Access metadata for the line_items array itself
  const lineItemsMetadata = output.metadata.line_items;

  // Loop through line items array
  for (let i = 0; i < output.value.line_items.length; i++) {
    const lineItemPath = `line_items[${i}]`;

    // Access the line item object and its metadata
    const lineItem = output.value.line_items[i];
    const lineItemMetadata = output.metadata[lineItemPath];

    // Access properties within the line item and their metadata
    const lineItemDescription = lineItem.description;
    const lineItemDescriptionMetadata =
      output.metadata[`${lineItemPath}.description`];
    const lineItemQuantity = lineItem.quantity;
    const lineItemQuantityMetadata = output.metadata[`${lineItemPath}.quantity`];
    const lineItemPrice = lineItem.price;
    const lineItemPriceMetadata = output.metadata[`${lineItemPath}.price`];
  }
  ```

  ```python Python Example theme={null}
  output = {
    "value": {
      "invoice_number": "INV-123",
      "line_items": [
        { "description": "Item A", "quantity": 2, "price": 10.0 },
        { "description": "Item B", "quantity": 1, "price": 25.5 },
      ],
    },
    "metadata": {
      "invoice_number": {
        "logprobsConfidence": 1,
        "ocrConfidence": 0.99,
        "citations": [{ "referenceText": "Invoice #: INV-123" }],
      },
      "line_items": {
        "logprobsConfidence": 0.98, # Metadata for the array itself
        "ocrConfidence": 0.98,
      },
      "line_items[0]": {
        "logprobsConfidence": 0.98, # Metadata for the first object in the array
        "ocrConfidence": 0.98,
        "citations": [{ "page": 1 }],
      },
      "line_items[0].description": { "logprobsConfidence": 1, "ocrConfidence": 0.95 },
      "line_items[0].quantity": { "logprobsConfidence": 1, "ocrConfidence": 0.98 },
      "line_items[0].price": { "logprobsConfidence": 1, "ocrConfidence": 0.98 },
      "line_items[1].description": { "logprobsConfidence": 1, "ocrConfidence": 0.96 },
      # Other metadata entries...
    },
  }

  # Traversing the output object and accessing metadata
  # Use .get() for safe access in case keys are missing

  # Access root level value and its metadata
  invoice_number = output.get("value", {}).get("invoice_number")
  invoice_number_metadata = output.get("metadata", {}).get("invoice_number")

  # Access metadata for the line_items array itself
  line_items_metadata = output.get("metadata", {}).get("line_items")

  # Loop through line items array
  line_items = output.get("value", {}).get("line_items", [])
  for i, line_item in enumerate(line_items):
      line_item_path = f"line_items[{i}]"

      # Access the line item object and its metadata
      item_metadata = output.get("metadata", {}).get(line_item_path)

      # Access properties within the line item and their metadata
      description = line_item.get("description")
      description_metadata = output.get("metadata", {}).get(f"{line_item_path}.description")
      quantity = line_item.get("quantity")
      quantity_metadata = output.get("metadata", {}).get(f"{line_item_path}.quantity")
      price = line_item.get("price")
      price_metadata = output.get("metadata", {}).get(f"{line_item_path}.price")
  ```
</CodeGroup>

### Examples

<Accordion title="Basic Field Types">
  ```json theme={null}
  {
    "value": {
      "amount": {
        "amount": 15735.1,
        "iso_4217_currency_code": "USD"
      },
      "invoice_number": "36995"
    },
    "metadata": {
      "amount": {
        "insights": [
          {
            "type": "reasoning",
            "content": "The total amount is shown as '$15,735.1' in both the table summary and the bottom right of the document. The currency symbol '$' and the US address indicate the currency is USD. The value is numeric and matches the required format."
          }
        ],
        "citations": [
          {
            "page": 1,
            "polygon": [
              {
                "x": 430.164,
                "y": 722.772
              },
              {
                "x": 467.27279999999996,
                "y": 722.8296
              },
              {
                "x": 467.2584,
                "y": 731.6351999999999
              },
              {
                "x": 430.1496,
                "y": 731.5776
              }
            ],
            "referenceText": "TOTAL  $15,735.1"
          }
        ],
        "ocrConfidence": 0.992,
        "logprobsConfidence": 1
      },
      "invoice_number": {
        "insights": [
          {
            "type": "reasoning",
            "content": "The invoice number is clearly labeled as 'Invoice #36995' at the top right of the document, making it straightforward to extract."
          }
        ],
        "citations": [
          {
            "page": 1,
            "polygon": [
              {
                "x": 296.73359999999997,
                "y": 40.888799999999996
              },
              {
                "x": 386.4168,
                "y": 40.464000000000006
              },
              {
                "x": 386.4744,
                "y": 52.1712
              },
              {
                "x": 296.7912,
                "y": 52.596000000000004
              }
            ],
            "referenceText": "Invoice #36995"
          }
        ],
        "ocrConfidence": 0.986,
        "logprobsConfidence": 1
      }
    }
  }
  ```
</Accordion>

<Accordion title="Nested Structures">
  ```json theme={null}
  {
    "value": {
      "line_items": [
        {
          "item": "Widget A",
          "quantity": 5,
          "price": {
            "amount": 10.0,
            "iso_4217_currency_code": "USD"
          }
        },
        {
          "item": "Widget B",
          "quantity": 2,
          "price": {
            "amount": 15.0,
            "iso_4217_currency_code": "USD"
          }
        }
      ],
      "signature_block": {
        "printed_name": "John Smith",
        "signature_date": "2024-03-15",
        "is_signed": true,
        "title_or_role": "Purchasing Manager"
      }
    },
    "metadata": {
      "line_items": {
        "logprobsConfidence": 0.96 // Minimum confidence for the values in the array
      },
      "line_items[0]": {
        "logprobsConfidence": 0.96, // Minimum confidence for the values in the item
        "page": 1
      },
      "line_items[0].item": {
        "logprobsConfidence": 0.99
      },
      "line_items[0].quantity": {
        "logprobsConfidence": 1.0
      },
      "line_items[0].price.amount": {
        "logprobsConfidence": 0.98
      },
      "line_items[0].price.iso_4217_currency_code": {
        "logprobsConfidence": 0.96
      },
      "line_items[1]": {
        "logprobsConfidence": 0.96,
        "page": 1
      },
      "line_items[1].item": {
        "logprobsConfidence": 0.98
      },
      "line_items[1].quantity": {
        "logprobsConfidence": 1.0
      },
      "line_items[1].price.amount": {
        "logprobsConfidence": 0.97
      },
      "line_items[1].price.iso_4217_currency_code": {
        "logprobsConfidence": 0.96
      },
      "signature_block": {
        "logprobsConfidence": 0.99, // Confidence for the overall object
        "citations": [
          {
            "page": 1,
            "referenceText": "John Smith",
            "polygon": [
              /* points omitted */
            ]
          }
        ]
      }
    }
  }
  ```
</Accordion>

## Extraction output type (Fields Array)

<Note>
  This section is relevant for the Fields Array config type. If you are using
  the JSON Schema config type, please see the [Extraction output type (JSON
  Schema)](#extraction-output-type-json-schema) documentation. If you aren't
  sure which config type you are using, please see the [Migrating to JSON
  Schema](/product-reference/studio/migrating_to_json_schema) documentation.
</Note>

For processors using the legacy Fields Array configuration, the extraction output is a flat dictionary where each key is the `fieldName` (or sometimes the `id` if names aren't unique) you defined in the configuration, and the value is an `ExtractionFieldResult` object containing the extracted data and associated details.

### Type definition

Each `ExtractionFieldResult` object contains the core `id`, `type`, and extracted `value`. It can also include the following optional details:

* `schema`: The schema definition for nested fields (like objects or array items).
* `insights`: Reasoning or explanations from the model (if enabled).
* `references`: Location information, including the page number and specific **Bounding Boxes** relevant to the legacy Fields Array configuration (see [Bounding Boxes Guide](/api-reference/guides/bounding_boxes#bounding-box-schema-fields-array-config)).
* `enum`: The available options if the field type is `enum`.

```typescript theme={null}
type ExtractionOutput = {
  [fieldName: string]: ExtractionFieldResult;
};

type ExtractionFieldResult = {
  id: string;
  type:
    | "string"
    | "number"
    | "currency"
    | "boolean"
    | "date"
    | "enum"
    | "array"
    | "object"
    | "signature";
  value:
    | string
    | number
    | Currency
    | boolean
    | Date
    | ExtractionValueArray
    | ExtractionValueObject
    | Signature
    | null;

  /* The following fields are included in outputs, but not required for creating an evaluation set item */

  /* Includes the field schema of nested fields (e.g. array fields, object fields, signature fields etc) */
  schema: ExtractionFieldSchemaValue[];

  /* Insights the reasoning and other insights outputs of the model (when reasoning is enabled) */
  insights: Insight[];

  /* References for the extracted field, always includes the page number for all fields, and might include bounding boxes and citations when available. */
  references: ExtractionFieldResultReference[];

  /* The enum options for enum fields, only set when type=enum */
  enum: EnumOption[];
};

type Currency = {
  amount: number;
  iso_4217_currency_code: string;
};

type Signature = {
  printed_name: string;
  signature_date: string;
  is_signed: boolean;
  title_or_role: string;
};

type EnumOption = {
  value: string; // The enum value (e.g. "ANNUAL", "MONTHLY", etc.)
  description: string; // The description of the enum value
};

type ExtractionValueArray = Array<ExtractionValueObject>;
type ExtractionValueObject = Record<string, any>;
```

#### References

```typescript theme={null}
type ExtractionFieldResultReference = {
  /* The field id. When nested for arrays, this is the index of the row number */
  id: string;
  /* The field name */
  fieldName: string;
  /* The page number (starting at 1) that this bounding box is from */
  page: number;
  /**
   * Array of bounding box references for this field.
   * There can be multiple is the extraction result was drawn from multiple distinct sources on the page.
   */
  boundingBoxes: BoundingBox[];
};

/* See the Bounding boxes guide for information on how to use/interpret this data */
type BoundingBox = {
  /* The left most position of the bounding box */
  left: number;
  /* The top most position of the bounding box */
  top: number;
  /* The right most position of the bounding box */
  right: number;
  /* The bottom most position of the bounding box */
  bottom: number;
};
```

### Examples

<Accordion title="Basic Field Types">
  ```json theme={null}
  {
    "invoice_number": {
      "id": "field_123",
      "type": "string",
      "value": "INV-2024-001"
    },
    "amount_due": {
      "id": "field_456",
      "type": "currency",
      "value": {
        "amount": 1250.5,
        "iso_4217_currency_code": "USD"
      }
    }
  }
  ```
</Accordion>

<Accordion title="Nested Structures with References and Insights">
  ```json theme={null}
  {
    "line_items": {
      "id": "field_789",
      "type": "array",
      "value": [
        {
          "item": "Widget A",
          "quantity": 5,
          "price": {
            "amount": 10.0,
            "iso_4217_currency_code": "USD"
          }
        },
        {
          "item": "Widget B",
          "quantity": 2,
          "price": {
            "amount": 15.0,
            "iso_4217_currency_code": "USD"
          }
        }
      ],
      "schema": [
        // Schema definition for the items in the array
        {
          "id": "item",
          "name": "Item Name",
          "type": "string",
          "description": "..."
        },
        {
          "id": "quantity",
          "name": "Quantity",
          "type": "number",
          "description": "..."
        },
        {
          "id": "price",
          "name": "Price",
          "type": "currency",
          "description": "..."
        }
      ]
    },
    "signature_block": {
      "id": "field_101",
      "type": "signature",
      "value": {
        "printed_name": "John Smith",
        "signature_date": "2024-03-15",
        "is_signed": true,
        "title_or_role": "Purchasing Manager"
      },
      "schema": [
        // Schema for the signature object fields
        {
          "id": "printed_name",
          "name": "Printed Name",
          "type": "string",
          "description": "..."
        },
        {
          "id": "signature_date",
          "name": "Signature Date",
          "type": "date",
          "description": "..."
        },
        {
          "id": "is_signed",
          "name": "Is Signed",
          "type": "boolean",
          "description": "..."
        },
        {
          "id": "title_or_role",
          "name": "Title/Role",
          "type": "string",
          "description": "..."
        }
      ],
      "insights": [
        {
          "type": "reasoning",
          "content": "Signature block found at the bottom of page 2. 'is_signed' is true based on visual confirmation."
        }
      ],
      "references": [
        {
          "id": "signature_block", // Refers to the top-level field ID
          "fieldName": "Signature Block",
          "page": 2,
          "boundingBoxes": [
            // Box around the whole signature area
            { "left": 100, "top": 700, "right": 400, "bottom": 780 }
          ]
        }
      ]
    }
  }
  ```
</Accordion>

## Classification Output Type

### Type Definition

```typescript theme={null}
type ClassificationOutput = {
  id: string;
  type: string;
};
```

### Example

```json theme={null}
{
  "id": "classification_123",
  "type": "INVOICE"
}
```

## Splitter Output Type

### Type Definition

```typescript theme={null}
type SplitterOutput = {
  subDocuments: SubDocument[];
};

type SubDocument = {
  classificationId: string; // The id of the classification type (set in the processor config)
  type: string; // The type of the split document (set in the processor config), corresponds to the classificationId.
  startPage: number; // The start page of the split document
  endPage: number; // The end page of the split document

  // Fields included in outputs, but not required for creating an evaluation set item
  identifier?: string; // Identifier for the split document (e.g. invoice number)
  observation?: string; // Explanation of the results
};
```

### Example

```json theme={null}
{
  "subDocuments": [
    {
      "classificationId": "invoice",
      "type": "invoice",
      "startPage": 1,
      "endPage": 3
    },
    {
      "classificationId": "other",
      "type": "other",
      "startPage": 4,
      "endPage": 5
    }
  ]
}
```

## Shared Types

Certain types are shared across different processor outputs. These provide additional context and information about the processor's decisions.

### Type Definition

```typescript theme={null}
type Insight = {
  type: "reasoning"; // Currently only reasoning is supported
  content: string; // The explanation or reasoning provided by the model
};
```

### Example

```json theme={null}
{
  "insights": [
    {
      "type": "reasoning",
      "content": "This was classified as an invoice because it contains standard invoice elements including an invoice number, billing details, and itemized charges."
    }
  ]
}
```

Insights can appear in both Extraction and Classification outputs to provide transparency into the model's decision-making process. They are particularly useful when debugging or validating processor results.