{"componentChunkName":"component---src-templates-simple-markdown-js","path":"/docs/ai/document-ai/extraction-schemas/","matchPath":"","result":{"data":{"markdownRemark":{"html":"

Extraction Schemas

\n

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

\n

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

\n

Anatomy of a schema

\n
\n
\n
Copy
\n
Copied
\n
\n 
{\n  \"name\": \"purchase_order_number\",\n  \"prompt\": \"Extract the purchase order number. Return null when absent.\",\n  \"json_schema\": {\n    \"type\": [\"string\", \"null\"]\n  },\n  \"scope\": \"document\",\n  \"result_cardinality\": \"single\",\n  \"include_source_regions\": true\n}
\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FieldPurpose
nameStable key used to identify the result.
promptFocused instructions describing what to extract.
json_schemaJSON Schema defining the expected value.
scopeExtract once per document or independently per segment.
result_cardinalityReturn a single result or multiple independent matches.
include_source_regionsInclude normalized source locations when available.
\n

See Configuration Reference for defaults and complete field definitions.

\n

Design a stable result

\n

Choose a name

\n

Use stable snake_case names such as:

\n\n

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

\n

Write a focused prompt

\n

A good prompt:

\n\n
\n
\n
Copy
\n
Copied
\n
\n 
Extract the bill of lading number from the document header.\nReturn null when no bill of lading number is present.\nDo not return shipment, invoice, or purchase order numbers.
\n
\n

Define the JSON shape

\n

Use the narrowest shape that supports your workflow.

\n

Simple value:

\n
\n
\n
Copy
\n
Copied
\n
\n 
{\n  \"type\": [\"string\", \"null\"]\n}
\n
\n

Object:

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

Array:

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

Scope and cardinality

\n

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

\n

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

\n

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

\n

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.

\n

Source regions

\n

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

\n
\n
\n
Copy
\n
Copied
\n
\n 
{\n  \"left\": 0.12,\n  \"top\": 0.41,\n  \"width\": 0.28,\n  \"height\": 0.04\n}
\n
\n

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

\n

Generate a schema starting point

\n

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

\n

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

\n

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

\n

Test before production

\n
    \n
  1. \nTest representative layouts from every expected source.\n
    2. \n
  2. \nTest absent, malformed, ambiguous, and repeated values.\n
    3. \n
  3. \nValidate each returned \nvalue\n against your expected JSON Schema.\n
    4. \n
  4. \nReview source regions when enabled.\n
    5. \n
  5. \nTest the configuration against documents it should reject or leave empty.\n
    6. \n
  6. \nVersion consuming integrations before renaming or reshaping schemas.\n
    7. \n
\n

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

","headings":[{"value":"Extraction Schemas","depth":1},{"value":"Anatomy of a schema","depth":2},{"value":"Design a stable result","depth":2},{"value":"Choose a name","depth":3},{"value":"Write a focused prompt","depth":3},{"value":"Define the JSON shape","depth":3},{"value":"Scope and cardinality","depth":2},{"value":"Source regions","depth":2},{"value":"Generate a schema starting point","depth":2},{"value":"Test before production","depth":2}]},"contentItem":{"data":{"lastModified":"2026-07-17T16:00:10.000Z","enableToc":null,"disableLastModified":null,"tocMaxDepth":null,"requestLogin":false}},"siteConfig":{"enableToc":true,"disableLastModified":false,"tocMaxDepth":4}},"pageContext":{"matchPath":"","id":"b0821da9-88f9-589b-8993-8e058df46700__redocly content/docs/ai/document-ai/extraction-schemas/","seo":{"title":"Extraction Schemas","description":null,"image":"","keywords":null,"jsonLd":null,"lang":null,"siteUrl":null},"pageId":"docs/ai/document-ai/extraction-schemas.md","pageBaseUrl":"/docs/ai/document-ai/extraction-schemas","type":"markdown","toc":{"enable":true,"maxDepth":4,"headings":[{"depth":1,"value":"Extraction Schemas","id":"extraction-schemas"},{"depth":2,"value":"Anatomy of a schema","id":"anatomy-of-a-schema"},{"depth":2,"value":"Design a stable result","id":"design-a-stable-result"},{"depth":3,"value":"Choose a name","id":"choose-a-name"},{"depth":3,"value":"Write a focused prompt","id":"write-a-focused-prompt"},{"depth":3,"value":"Define the JSON shape","id":"define-the-json-shape"},{"depth":2,"value":"Scope and cardinality","id":"scope-and-cardinality"},{"depth":2,"value":"Source regions","id":"source-regions"},{"depth":2,"value":"Generate a schema starting point","id":"generate-a-schema-starting-point"},{"depth":2,"value":"Test before production","id":"test-before-production"}]},"data":{"title":"Extraction Schemas"},"catalogInfo":null,"link":"/docs/ai/document-ai/extraction-schemas/","sidebarName":"developerPortal","isLanding":false,"showPrevButton":null,"showNextButton":null,"apiVersions":null,"apiVersionId":null,"isDefaultApiVersion":null}},"staticQueryHashes":["1123603147","1302185487","1344209882","1398840060","1520077861","1975142765","2667623876","2950305614","3240152602","3743992808","561138138"]}