Custom extraction with blueprints
A blueprint tells Amazon Textract Insights which fields to extract from a document and returns the result as structured data keyed by your field names. Attach one or more blueprints to a project, or pass them inline on a job, to get custom extraction results in addition to (or instead of) extraction.
Blueprints come in two kinds: public blueprints that AWS maintains for common document types, and custom blueprints that you define with your own schema.
Without splitting enabled, custom extraction has a maximum number of pages supported per document. For longer files, enable splitting so the file is divided into individual documents before blueprints are applied. See Splitting multi-document files and Limits and quotas.
Public blueprints
Public blueprints are managed by AWS and cover widely used document types. You do not create or version them; you reference them by ARN. Each public blueprint ARN has the form:
arn:aws:textract:<region>:aws:blueprint/<name>
For example, the W-2 blueprint in US East (N. Virginia) is
arn:aws:textract:us-east-1:aws:blueprint/public-w2-form.
To list the public blueprints available in an AWS Region, call ListBlueprints
with the service resource owner:
aws textract list-blueprints \ --resource-owner SERVICE \ --region us-east-1
The following public blueprints are currently available.
Document type |
Blueprint ARN |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Replace <region> with the AWS Region you call, for example
us-east-1.
Custom blueprints
When no public blueprint matches your document, or you need a different set of fields, define a custom blueprint with your own JSON schema. The schema lists the fields to extract, their data types, and natural-language descriptions that guide the model. For the schema format and the commands to create, update, get, list, and delete blueprints, see Creating blueprints. For how to adapt the examples on this page to real documents, see Blueprint schemas.
Custom extraction result.json field reference
When a document matches a blueprint, Amazon Textract Insights writes a custom
extraction result.json at
<prefix>/<job-id>/<asset-id>/custom/<n>/result.json,
where <n> is the index of the matched sub-document. The file has the
following top-level structure.
Field |
Description |
|---|---|
|
The blueprint that matched this document: |
|
The document class, with |
|
|
|
The extracted field values, keyed by your schema. Scalar fields
hold strings, numbers, or booleans; tables are arrays of row
objects; nested groups are objects. A field that was not found holds
an empty string ( |
|
An array that mirrors |
inference_result
inference_result is keyed exactly by the property names in your
blueprint schema. The following example is trimmed custom extraction results from
the public W-2 blueprint, with sample values replaced by placeholders.
{ "matched_blueprint": { "arn": "arn:aws:textract:us-east-1:aws:blueprint/public-w2-form", "name": "W2-Form", "confidence": 1 }, "document_class": { "type": "W2" }, "split_document": { "page_indices": [0, 1] }, "inference_result": { "employee_general_info": { "first_name": "Jane", "employee_last_name": "Doe", "employee_address": "123 Any Street, Anytown, WA 98101", "employee_zip_code": 98101, "ssn": "123-45-6789" }, "employer_info": { "employer_name": "Example Corp", "ein": "12-3456789", "control_number": "" }, "federal_wage_info": { "wages_tips_other_compensation": 68450, "social_security_wages": 68450 } } }
Note how control_number was not present on the document and is
returned as an empty string.
explainability_info
explainability_info is an array whose entries mirror the shape of
inference_result. Each leaf field is replaced by an object with the
following keys.
Field |
Description |
|---|---|
|
|
|
Model confidence for the value, from 0 to 1. |
|
The field's schema type, for example |
|
The extracted value (empty string when not found). |
|
An array of locations on the page. Each entry has
|
The following is a single leaf from explainability_info, trimmed.
{ "employer_info": { "employer_name": { "success": true, "confidence": 0.9030104875564575, "type": "string", "value": "Example Corp", "geometry": [ { "boundingBox": { "top": 0.1274, "left": 0.0660, "width": 0.1928, "height": 0.0100 }, "page": 1, "word_references": [ { "word_index": 29, "page_index": 0 } ] } ] } } }
Confidence-based routing
Because explainability_info carries a confidence per field, you can
route individual fields to human review rather than accepting or rejecting the whole
document. A common pattern is to pick a confidence threshold, pass fields at or above
it straight to downstream processing, and queue fields below it for a human to
confirm. Field confidences vary within a single document, so this lets you
auto-process high-confidence fields while catching the few that need attention.
For how to detect and mask personal data in output, see Detecting and redacting sensitive data. For request parameters and errors, see the Amazon Textract Insights API Reference.