Best Practices

Good schemas describe the data that appears in the source document. They should not ask the model to calculate new values, infer unsupported data, or transform results that can be handled downstream.

Use field names that match the document

Field names should be specific and close to the wording in the source document.

Avoid	Prefer
`amount`	`invoice_total`
`date`	`invoice_date`
`name`	`vendor_name`
`id`	`purchase_order_number`

Specific field names reduce ambiguity and make the output easier to use downstream.

Write precise field descriptions

Descriptions help the extraction model choose the correct value when a document contains similar fields.

Weak description	Better description
`Amount`	`The total amount including tax`
`Date`	`The invoice issue date`
`Company`	`The vendor or merchant name`
`Address`	`The billing address of the buyer`

Include units, date meaning, currency expectations, and business context when they matter.

Use enums for known values

Use enum fields when the output should be one of a known set of values. In the schema JSON used by Extract, enum fields can constrain the output to a predefined set of allowed values.

{
  "payment_status": {
    "type": ["enum", "null"],
    "enum": ["Paid", "Pending", "Overdue", "Cancelled"],
    "description": "The payment status shown in the document"
  }
}

Enums improve consistency and reduce variation in downstream systems.

Keep schemas simple

Use the simplest structure that matches the data you need. Avoid deep nesting unless the source document actually contains nested information. Deep schemas are harder to maintain and can make extraction less reliable. The examples below show field definitions inside the properties object, not complete top-level schemas. Recommended:

{
  "vendor_name": {
    "type": ["string", "null"],
    "description": "The vendor name"
  },
  "vendor_tax_id": {
    "type": ["string", "null"],
    "description": "The vendor tax ID"
  }
}

Use a nested object only when grouping fields improves clarity:

{
  "vendor": {
    "type": "object",
    "description": "Vendor information",
    "properties": {
      "name": {
        "type": ["string", "null"],
        "description": "The vendor name"
      },
      "tax_id": {
        "type": ["string", "null"],
        "description": "The vendor tax ID"
      }
    },
    "required": ["name", "tax_id"]
  }
}

Use arrays for repeated data

Use arrays when the document contains repeated values or table rows. The example below shows a field definition inside the properties object, not a complete top-level schema.

{
  "line_items": {
    "type": "array",
    "description": "Invoice line items",
    "items": {
      "type": "object",
      "properties": {
        "description": {
          "type": ["string", "null"],
          "description": "Line item description"
        },
        "quantity": {
          "type": ["number", "null"],
          "description": "Line item quantity"
        },
        "amount": {
          "type": ["number", "null"],
          "description": "Line item amount"
        }
      },
      "required": ["description", "quantity", "amount"]
    }
  }
}

Use arrays for:

Invoice line items
Order lists
Product lists
Tables with repeated rows
Multiple addresses, contacts, or identifiers

Do not ask the schema to calculate new values

The schema should describe values that appear in the source document. Do calculations in your application after extraction. Avoid:

{
  "annual_cost": {
    "type": ["number", "null"],
    "description": "Monthly cost multiplied by 12"
  }
}

Prefer:

{
  "monthly_cost": {
    "type": ["number", "null"],
    "description": "The monthly service cost"
  }
}

Then calculate downstream:

annual_cost = result["monthly_cost"] * 12

Use nullable fields

Use nullable field types when a value may not appear in every document.

{
  "purchase_order_number": {
    "type": ["string", "null"],
    "description": "The purchase order number"
  }
}

This makes the schema more permissive when a field may be absent.

In current Extract responses, missing values may still appear as empty strings or empty arrays rather than null, depending on the field and the returned output.

Test with representative documents

Test schemas with documents that reflect real production inputs:

Different vendors or document templates
Scanned and digital documents
Short and long documents
Documents with missing fields
Documents with tables or repeated rows

Review both extracted values and citations when available.

Iterate on the schema

If extraction quality is poor:

Make field names more specific.
Add clearer descriptions.
Use enums for fixed categories.
Split ambiguous fields into separate fields.
Simplify nested structures.
Test with more representative examples.

Extract Quickstart

Extract your first document.

Schema Guide

Create extraction schemas.

Response Format

Understand the output.

Getting Started

Parse

Extract

Use field names that match the document

Write precise field descriptions

Use enums for known values

Keep schemas simple

Use arrays for repeated data

Do not ask the schema to calculate new values

Use nullable fields

Test with representative documents

Iterate on the schema

Extract Quickstart

Schema Guide

Response Format

​Use field names that match the document

​Write precise field descriptions

​Use enums for known values

​Keep schemas simple

​Use arrays for repeated data

​Do not ask the schema to calculate new values

​Use nullable fields

​Test with representative documents

​Iterate on the schema

​Related resources

Extract Quickstart

Schema Guide

Response Format

Use field names that match the document

Write precise field descriptions

Use enums for known values

Keep schemas simple

Use arrays for repeated data

Do not ask the schema to calculate new values

Use nullable fields

Test with representative documents

Iterate on the schema

Related resources