Taxonomies & Tags

Tags are the metadata attributes you want to extract or classify from your documents. Taxonomies organize tags into hierarchical structures that define parent-child relationships.

What is a Tag?

A Tag defines a specific piece of information you want to capture from documents:

Property	Description	Example
Name	The tag identifier	`Contract Type`
Description	Instructions for the AI on what to extract	”Identify the type of legal agreement (NDA, MSA, SOW, etc.)”
Output Type	How values are returned	String, Binary, Number, Date
Max Values	How many values get returned	1 to however many relevant values an AI can find
Available Values	Predefined options (for classification)	`["NDA", "MSA", "SOW", "Employment Agreement"]`
Strategy	Extraction method	LLM (AI), Regex (Pattern), Rule-based

Tag Types

Tag Type	How It Works	When to Use	Example
Classification Tags	AI chooses from predefined list of values	When you have a known set of categories	Document Type: Contract, Invoice, Report
Extraction Tags	AI extracts open-ended values from text	When the value is unpredictable	Contract Value: $1,500,000
Pattern Tags	Regex plus context keywords that must appear nearby	For compliance, keyword-search, etc.	SSN: XXX-XX-XXXX, Email: [email protected]

Classification is best when you have a known set of categories. Extraction is best for unpredictable values like names, dates, or amounts. Pattern is best for structured data like phone numbers or SSNs.

Three Ways to Define a Tag

Every tag resolves its value through one of three strategies:

Strategy	How the value is decided	Cost	Example
AI (LLM)	The model reads the document and follows your description	LLM call per document	`summary`, `contract_type`
Pattern (Regex + context)	Deterministic matching, corroborated by context keywords	No LLM	`ssn_matches`, employee IDs
Rule-based	Deterministic conditions over other tags’ values	No LLM	`AI Agent Access = Restricted` if `PII = true`

Pattern tags are not bare regex. Each pattern carries context keywords (context_items) and a required_context_matches threshold: a nine-digit number only counts as an SSN when words like “social security” or “SSN” appear near it. That corroboration is what keeps precision high on real documents, and the platform can suggest both the pattern and its context keywords from your data. See Precision Patterns for Sensitive Data. Rule-based tags evaluate after their input tags exist: if a rule matches, the value is resolved deterministically; if no rule matches, the tag falls back to its other configured strategy, pattern matching or LLM classification, depending on the tag definition. Because rules run at zero LLM cost, they are the right tool for policy verdicts derived from other signals (access gates, retention classes, readiness flags).

Taxonomy Structure

A Taxonomy enables hierarchical organization and conditional extraction. Child tags only get generated when parent conditions are met:

Document Type (Classification: Contract | Invoice | Report)
├── Contract
│   ├── Contract Value (Extraction)
│   ├── Parties Involved (Extraction)
│   ├── Effective Date (Extraction)
│   └── Termination Date (Extraction)
├── Invoice
│   ├── Invoice Amount (Extraction)
│   ├── Due Date (Extraction)
│   └── Vendor Name (Extraction)
└── Report
    ├── Report Category (Classification: Financial | Operational | Compliance)
    └── Report Period (Extraction)

In this taxonomy, the AI first classifies the document type, then only extracts the relevant child tags. A Contract won’t have “Invoice Amount” extracted, which saves time and cost.

Creating Effective Tags

Define Clear Descriptions

Give the AI specific instructions about what to extract. The better your description, the more accurate the extraction.

Choose the Right Type

Use Classification for known categories, Extraction for open-ended values, and Pattern for structured formats.

Set Available Values

For Classification tags, provide a complete list of possible values to improve accuracy.

Organize into Taxonomies

Group related tags hierarchically to enable conditional extraction and reduce unnecessary processing.

Python SDK

Create Tags
Create Taxonomy
Pattern & Rule Tags
AI Suggestions
List & Delete

from unstructured import UnstructuredClient

client = UnstructuredClient(
    base_url="https://unstructured.your-company.com/rest/unstructured",
    username="your-username",
    password="your-password",
)

# Create or update tags, the metadata attributes you want to extract
for tag in [
    {
        "name": "contract_type",
        "description": "Type of contract (NDA, MSA, SLA, etc.)",
        "output_type": "string",
        "available_values": ["NDA", "MSA", "SLA", "Employment Agreement"],
    },
    {
        "name": "parties",
        "description": "Names of all parties involved",
        "output_type": "string",
        "max_values": 10,
    },
    {
        "name": "effective_date",
        "description": "When the contract becomes effective",
        "output_type": "date",
    },
    {
        "name": "total_value",
        "description": "Total monetary value in USD",
        "output_type": "number",
    },
]:
    result = client.tags.upsert(tag_data=tag)

# Organize tags into a taxonomy, a node/edge graph where child tags
# are only extracted when the parent condition is met
taxonomy = client.taxonomy.upsert(
    taxonomy_name="contract-analysis",
    taxonomy_description="Extract key data from legal contracts",
    taxonomy_data={
        "nodes": [
            {"node_id": "1", "name": "contract_type",
             "active_values": ["NDA", "MSA", "SLA"]},
            {"node_id": "2", "name": "total_value"},
        ],
        "edges": [
            # Only extract total_value for MSA contracts
            {"target_node_ids": ["2"],
             "conditions": [{"node_id": "1", "tag_value_name": "MSA"}]},
        ],
    },
)

# Pattern tag: deterministic regex matching, no LLM cost
client.tags.upsert(tag_data={
    "name": "ssn_matches",
    "description": "US Social Security Numbers found in the document",
    "output_type": "string",
    "patterns": [{"pattern": r"\b\d{3}-\d{2}-\d{4}\b"}],
})

# Rule-based tag: a deterministic verdict derived from other tags.
# If a rule matches, the value resolves with no LLM call; if none
# match, the tag falls back to its other configured strategy
# (pattern matching or LLM classification, per the tag definition).
client.tags.upsert(tag_data={
    "name": "AI Agent Access",
    "description": "Whether AI agents may access this document",
    "output_type": "string",
    "available_values": ["Restricted", "Allowed"],
    "visual_rules": [
        {
            "condition": {
                "condition": "OR",
                "children": [
                    {"tag": {"name": "PII (Personally Identifiable Information)",
                             "operator": "in", "values": ["true"]}},
                    {"tag": {"name": "PHI (Protected Health Information)",
                             "operator": "in", "values": ["true"]}},
                ],
            },
            "tag_value": "Restricted",
        },
    ],
})

# Get an AI-suggested taxonomy based on your actual documents
suggestion = client.taxonomy.suggest(
    data_connector_name="my-s3-bucket",
    user_context="Medical patient records with diagnoses and prescriptions",
)
print(suggestion.suggestion)

# Get an AI-suggested regex pattern for a Pattern tag
pattern = client.tags.pattern.suggest_patterns(
    pattern_description="US Social Security Number (XXX-XX-XXXX)",
    tag_data={"name": "ssn", "description": "US Social Security Number"},
)
print(f"Suggested pattern: {pattern.regex} (confidence: {pattern.confidence_score})")

# List all taxonomies
taxonomies = client.taxonomy.list()
for t in taxonomies.taxonomies:
    print(t.taxonomy_name)

# List all tags
tags = client.tags.list()
for tag in tags.tags:
    print(f"{tag.name} ({tag.output_type})")

# Delete a taxonomy
client.taxonomy.delete(taxonomy_name="old-taxonomy")

# Delete a tag
client.tags.delete(tag_name="unused-tag")

API Reference

Upsert Tag

Create or update a tag

List Tags

List all your tags

Delete Tag

Remove a tag

Suggest Patterns

AI-powered pattern suggestions

Upsert Taxonomy

Create or update a taxonomy

List Taxonomies

List all your taxonomies

Delete Taxonomy

Remove a taxonomy

Suggest Taxonomy

AI-powered taxonomy suggestions

Getting Started

Core Concepts

Cookbooks

Integrations

What is a Tag?

Tag Types

Three Ways to Define a Tag

Taxonomy Structure

Creating Effective Tags

Python SDK

API Reference

Upsert Tag

List Tags

Delete Tag

Suggest Patterns

Upsert Taxonomy

List Taxonomies

Delete Taxonomy

Suggest Taxonomy

​What is a Tag?

​Tag Types

​Three Ways to Define a Tag

​Taxonomy Structure

​Creating Effective Tags

​Python SDK

​API Reference

Upsert Tag

List Tags

Delete Tag

Suggest Patterns

Upsert Taxonomy

List Taxonomies

Delete Taxonomy

Suggest Taxonomy

What is a Tag?

Tag Types

Three Ways to Define a Tag

Taxonomy Structure

Creating Effective Tags

Python SDK

API Reference