Extraction Schemas

An extraction schema defines one structured value that Document AI should find and return.

Use schemas when an integration needs predictable JSON rather than only extracted text or a generated description.

Anatomy of a schema

Copy

Copied

{
  "name": "purchase_order_number",
  "prompt": "Extract the purchase order number. Return null when absent.",
  "json_schema": {
    "type": ["string", "null"]
  },
  "scope": "document",
  "result_cardinality": "single",
  "include_source_regions": true
}

Field	Purpose
`name`	Stable key used to identify the result.
`prompt`	Focused instructions describing what to extract.
`json_schema`	JSON Schema defining the expected value.
`scope`	Extract once per `document` or independently per `segment`.
`result_cardinality`	Return a `single` result or `multiple` independent matches.
`include_source_regions`	Include normalized source locations when available.

See Configuration Reference for defaults and complete field definitions.

Design a stable result

Choose a name

Use stable snake_case names such as:

purchase_order_number
invoice_total
line_items
delivery_date

Treat the name as part of your integration contract. Renaming a schema changes how consumers locate its result.

Write a focused prompt

A good prompt:

Identifies exactly one business concept
Explains how to distinguish similar values
Defines behavior when the value is absent
Requests the same shape defined by json_schema

Copy

Copied

Extract the bill of lading number from the document header.
Return null when no bill of lading number is present.
Do not return shipment, invoice, or purchase order numbers.

Define the JSON shape

Use the narrowest shape that supports your workflow.

Simple value:

Copy

Copied

{
  "type": ["string", "null"]
}

Object:

Copy

Copied

{
  "type": ["object", "null"],
  "properties": {
    "amount": {"type": "number"},
    "currency": {"type": "string"}
  },
  "required": ["amount", "currency"],
  "additionalProperties": false
}

Array:

Copy

Copied

{
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "description": {"type": "string"},
      "quantity": {"type": ["number", "null"]},
      "unit_price": {"type": ["number", "null"]}
    },
    "required": ["description"],
    "additionalProperties": false
  }
}

Scope and cardinality

Use scope: "document" for a value resolved once from the entire logical document, such as a document number, total, or primary party.

Use scope: "segment" when each independently processed segment can produce its own result.

Use result_cardinality: "single" when one answer is expected for the selected scope.

Use result_cardinality: "multiple" when several independent matches are expected. This differs from an array-valued schema: a single line_items result can contain an array while its result cardinality remains single.

Source regions

Enable include_source_regions when reviewers should trace a value to a PDF or image.

Copy

Copied

{
  "left": 0.12,
  "top": 0.41,
  "width": 0.28,
  "height": 0.04
}

Coordinates are normalized from 0 to 1, with the origin at the top-left. Text and spreadsheet formats can return source_regions: null.

Generate a schema starting point

Use the schema helper to create a draft JSON Schema from a natural-language request:

Send a name and prompt to POST /document-store/pipeline/schemas/generate.

The response contains json_schema and an explanatory rationale. Review and refine the generated schema before saving it.

Test before production

Test representative layouts from every expected source.
Test absent, malformed, ambiguous, and repeated values.
Validate each returned value against your expected JSON Schema.
Review source regions when enabled.
Test the configuration against documents it should reject or leave empty.
Version consuming integrations before renaming or reshaping schemas.

Use Custom Configurations to save reusable schemas or include them in a one-time pipeline_config.