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

Configuration Reference

\n

This page describes the customer-configurable fields used in pipeline_config.

\n

Pipeline configuration

\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
FieldTypeDefaultDescription
schemasarray[]Structured values to extract.
splitbooleanfalseDetect multiple logical documents in an eligible PDF and return separate result slices.
embedbooleantrueGenerate searchable representations for semantic search.
describeobjectDisabledConfigure automatic document descriptions.
\n

Only the fields documented here should be configured by customer applications. Model and provider selection are managed by Shipwell.

\n

Description configuration

\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
FieldTypeDefaultDescription
enabledbooleanfalseGenerate a natural-language document description.
promptstring or nullnullOptional instructions for the generated description.
key_factsbooleantrueInclude a compact set of important facts when description generation is enabled.
\n

Keep description prompts focused on purpose and audience. Put fields that must be consumed programmatically in schemas instead.

\n

Extraction schema

\n

Every item in schemas has the following customer-configurable fields:

\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\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FieldTypeRequiredDefaultDescription
namestringYes—Stable key used to identify the result.
promptstringYes—Instructions describing what to extract.
json_schemaobjectYes—JSON Schema describing the expected value.
scopesegment or documentNosegmentWhether extraction runs for each segment or once for the whole document.
result_cardinalitysingle or multipleNosingleWhether the schema returns one result or a list of matching results.
include_source_regionsbooleanNofalseInclude normalized source locations when available.
\n

Unknown fields are rejected.

\n

Name

\n

Choose a stable snake_case name such as:

\n\n

Treat the name as part of your integration contract. Changing it changes the key consumers use to find the extracted result.

\n

Prompt

\n

A good prompt:

\n\n

Example:

\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 or purchase order numbers.
\n
\n

JSON Schema

\n

Use JSON Schema to define the response type. Prefer the narrowest shape that supports your workflow.

\n

String or null:

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

Structured 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

List of line items:

\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

\n

Use document when the value should be resolved once from the entire logical document, such as:

\n\n

Use segment when each independently processed segment can produce its own value. This is especially useful when split processing is enabled.

\n

Result cardinality

\n

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

\n

Use multiple when several independent matches are expected. Define json_schema for one match; the result contains multiple schema-result entries.

\n

Do not use multiple only because the value itself is an array. A single extracted line_items value can use result_cardinality: \"single\" with an array-shaped json_schema.

\n

Source regions

\n

Set include_source_regions to true when a user should be able to trace an extracted value to its location.

\n

Regions use normalized coordinates:

\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 range from 0 to 1, with the origin at the top-left. Source regions are available for supported PDFs and images. They can be null for text and spreadsheet formats.

\n

Complete example

\n
\n
\n
Copy
\n
Copied
\n
\n 
{\n  \"schemas\": [\n    {\n      \"name\": \"bill_of_lading_number\",\n      \"prompt\": \"Extract the bill of lading number. Return null when absent.\",\n      \"json_schema\": {\"type\": [\"string\", \"null\"]},\n      \"scope\": \"document\",\n      \"result_cardinality\": \"single\",\n      \"include_source_regions\": true\n    },\n    {\n      \"name\": \"reference_numbers\",\n      \"prompt\": \"Extract each labeled reference number.\",\n      \"json_schema\": {\n        \"type\": \"object\",\n        \"properties\": {\n          \"label\": {\"type\": \"string\"},\n          \"value\": {\"type\": \"string\"}\n        },\n        \"required\": [\"label\", \"value\"],\n        \"additionalProperties\": false\n      },\n      \"scope\": \"document\",\n      \"result_cardinality\": \"multiple\",\n      \"include_source_regions\": true\n    }\n  ],\n  \"split\": false,\n  \"embed\": true,\n  \"describe\": {\n    \"enabled\": true,\n    \"prompt\": \"Summarize the document for an operations user.\",\n    \"key_facts\": true\n  }\n}
\n
\n

Validation guidance

\n

Before using a configuration in production:

\n
    \n
  1. \nTest representative layouts from every expected document source.\n
    2. \n
  2. \nTest missing, malformed, and repeated values.\n
    3. \n
  3. \nValidate result values against \njson_schema\n.\n
    4. \n
  4. \nReview source regions when enabled.\n
    5. \n
  5. \nVersion changes in the consuming integration before renaming or reshaping schemas.\n
    6. \n
","headings":[{"value":"Configuration Reference","depth":1},{"value":"Pipeline configuration","depth":2},{"value":"Description configuration","depth":2},{"value":"Extraction schema","depth":2},{"value":"Name","depth":3},{"value":"Prompt","depth":3},{"value":"JSON Schema","depth":3},{"value":"Scope","depth":3},{"value":"Result cardinality","depth":3},{"value":"Source regions","depth":3},{"value":"Complete example","depth":2},{"value":"Validation guidance","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":"c0d3353d-a120-55a8-a572-f9cb1258b1d8__redocly content/docs/ai/document-ai/configuration-reference/","seo":{"title":"Configuration Reference","description":null,"image":"","keywords":null,"jsonLd":null,"lang":null,"siteUrl":null},"pageId":"docs/ai/document-ai/configuration-reference.md","pageBaseUrl":"/docs/ai/document-ai/configuration-reference","type":"markdown","toc":{"enable":true,"maxDepth":4,"headings":[{"depth":1,"value":"Configuration Reference","id":"configuration-reference"},{"depth":2,"value":"Pipeline configuration","id":"pipeline-configuration"},{"depth":2,"value":"Description configuration","id":"description-configuration"},{"depth":2,"value":"Extraction schema","id":"extraction-schema"},{"depth":3,"value":"Name","id":"name"},{"depth":3,"value":"Prompt","id":"prompt"},{"depth":3,"value":"JSON Schema","id":"json-schema"},{"depth":3,"value":"Scope","id":"scope"},{"depth":3,"value":"Result cardinality","id":"result-cardinality"},{"depth":3,"value":"Source regions","id":"source-regions"},{"depth":2,"value":"Complete example","id":"complete-example"},{"depth":2,"value":"Validation guidance","id":"validation-guidance"}]},"data":{"title":"Configuration Reference"},"catalogInfo":null,"link":"/docs/ai/document-ai/configuration-reference/","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"]}