Blueprint matching and fallback blueprints
When a project or job provides more than one blueprint, Amazon Textract Insights matches each document (or each sub-document, when splitting is enabled) to the blueprint that best fits it, and extracts fields using that blueprint. A fallback blueprint lets you handle documents that do not match any of your primary blueprints.
How matching works
For each document, Amazon Textract Insights selects the matching blueprint and records
it in the custom result.json:
{ "matched_blueprint": { "arn": "arn:aws:textract:us-east-1:aws:blueprint/public-bank-statement", "name": "Bank-Statement", "confidence": 1 }, "document_class": { "type": "Bank-Statement" } }
-
matched_blueprint.arnandmatched_blueprint.nameidentify the blueprint that was used. -
matched_blueprint.confidenceis the match confidence, from 0 to 1. -
document_class.typeis the matched blueprint's class.
When splitting is enabled, matching runs per sub-document, so one input file can
produce several documents each matched to a different blueprint. In the observed
bank-statement-plus-invoice packet, sub-document 0 matched Bank-Statement
and sub-document 1 matched Invoice, each with a match confidence of 1. See
Splitting multi-document files.
Matching considers each blueprint's name, description, and fields, so blueprints with specific, descriptive names and descriptions match more reliably.
When no blueprint matches
job_metadata.json reports the outcome for each document in
custom_status:
custom_status |
Meaning |
|---|---|
|
A blueprint matched. The document has a |
|
No blueprint matched. The document has extraction results
( |
|
No primary blueprint matched, and the project's fallback
blueprint was used. The document has a |
A NO_MATCH document does not fail the job: the job still reaches
SUCCEEDED. Check custom_status for every entry in
segment_metadata rather than assuming each document has a
custom_path.
{ "segment_metadata": [ { "extraction_path": "s3://amzn-s3-demo-destination-bucket/results/<job-id>/0/extraction/0/result.json", "custom_status": "NO_MATCH" } ] }
Fallback blueprints
A fallback blueprint is used when a document does not match any of the project's
primary blueprints. Configure it in CustomConfiguration.FallbackBlueprints.
You can specify at most one fallback blueprint per project. See Limits and quotas. On UpdateProject, a
CustomConfiguration that omits FallbackBlueprints clears the
stored fallback blueprint.
aws textract create-project \ --project-name "mixed-documents" \ --extraction-configuration '{ "BoundingBox": { "State": "ENABLED" }, "Granularity": { "Types": ["DOCUMENT", "ELEMENT"] }, "OutputFormat": {"TextFormat": {"Types": ["MARKDOWN"]}, "AdditionalFileFormat": {"State": "DISABLED"}} }' \ --custom-configuration '{ "Blueprints": [ { "BlueprintArn": "arn:aws:textract:us-east-1:aws:blueprint/public-invoice" }, { "BlueprintArn": "arn:aws:textract:us-east-1:aws:blueprint/public-bank-statement" } ], "FallbackBlueprints": [ { "BlueprintArn": "arn:aws:textract:us-east-1:111122223333:blueprint/catch-all-blueprint" } ] }' \ --region us-east-1
Like primary blueprints, a fallback blueprint entry carries a BlueprintArn
and an optional BlueprintVersion. Use a fallback blueprint when your input
mix might include documents outside your known types and you still want a consistent set
of fields extracted from them.
Matching behavior by configuration
Whether matching runs, and what match confidence you get, depends on how many primary blueprints the project has and whether it has a fallback blueprint:
Configuration |
Matching behavior |
Match confidence |
|---|---|---|
One blueprint, no fallback |
Matching is skipped. Every document is extracted with the single blueprint. |
Always 1 |
One blueprint, with fallback |
Matching runs against the single blueprint. A document that doesn't match is extracted with the fallback blueprint. |
The match score, or 0 when the fallback is used |
Multiple blueprints, no fallback |
Matching runs against all blueprints and picks the best
match. A document that matches none gets |
The match score, or no custom results for
|
Multiple blueprints, with fallback |
Matching runs against all blueprints and picks the best match. A document that matches none is extracted with the fallback blueprint. |
The match score, or 0 when the fallback is used |
With a single blueprint, adding a fallback blueprint turns matching on, so
matched_blueprint.confidence reflects how well each document actually
fits the blueprint instead of always being 1.
How fallback results are reported
A document that matches none of the primary blueprints is processed with the fallback blueprint. Its results differ from a matched document in two ways:
-
In
job_metadata.json, the segment'scustom_statusisFALLBACK, notMATCH, andcustom_pathpoints at the custom extraction results as usual. -
In the custom extraction
result.json,matched_blueprintnames the fallback blueprint and its confidence is 0.
"segment_metadata": [ { "extraction_path": "s3://amzn-s3-demo-destination-bucket/results/abcd1234efgh/0/extraction/0/result.json", "custom_path": "s3://amzn-s3-demo-destination-bucket/results/abcd1234efgh/0/custom/0/result.json", "custom_status": "FALLBACK" } ]
If your code checks custom_status for MATCH before
reading custom_path, also accept FALLBACK, or the fallback
results are skipped.
Best practices for blueprint matching
To improve matching accuracy, follow these best practices:
-
Give each blueprint an explicit, descriptive name and description. Matching uses them.
-
Create separate blueprints for document formats that differ significantly.
-
Don't attach two blueprints for the same document type (for example, two W-2 blueprints) to one project. Overlapping blueprints compete during matching and reduce accuracy.
Choosing primary blueprints
Give the project the blueprints for the document types you expect. Public blueprints cover many common types (see Custom extraction with blueprints for the full list), and custom blueprints cover the rest (see Creating blueprints). Reserve the single fallback slot for documents that fall outside those types.
For the complete result.json field reference, including
explainability_info and per-field confidence, see Custom extraction with blueprints. For request
parameters and errors, see the Amazon Textract Insights API Reference.