Adding Validation Rules

Apply different validation rules based on document characteristics

This guide shows how to apply different validation rules based on document characteristics. For example, invoices from certain vendors might require additional approval fields, or documents above a threshold might need extra verification.

The Goal

Apply conditional validation:

• High-value invoices (over $10,000) require manager approval field
• International vendors require additional tax documentation fields
• Rush orders skip certain optional validations

What You’ll Create

Step 1: Create Feature Types

Invoice Value Tier

# kodexa-resources/knowledge-feature-types/invoice-value-tier.yaml
slug: invoice-value-tier
name: Invoice Value Tier
description: Categorization of invoices by total value

options:
  - name: tier
    type: string
    label: Value Tier
    description: The value tier (standard, high, critical)
    required: true

extendedOptions:
  - name: thresholdMin
    type: number
    label: Minimum Threshold
  - name: thresholdMax
    type: number
    label: Maximum Threshold

Vendor Location

# kodexa-resources/knowledge-feature-types/vendor-location.yaml
slug: vendor-location
name: Vendor Location
description: Geographic classification of vendor

options:
  - name: locationType
    type: string
    label: Location Type
    description: domestic or international
    required: true

extendedOptions:
  - name: country
    type: string
    label: Country
  - name: region
    type: string
    label: Region

Processing Priority

# kodexa-resources/knowledge-feature-types/processing-priority.yaml
slug: processing-priority
name: Processing Priority
description: Processing priority level

options:
  - name: priority
    type: string
    label: Priority
    description: standard, expedited, rush
    required: true

Step 2: Create the Validation Item Type

# kodexa-resources/knowledge-item-types/validation-rule.yaml
slug: validation-rule
name: Validation Rule
description: Define validation requirements for extracted data

options:
  - name: ruleType
    type: select
    label: Rule Type
    required: true
    options:
      - value: require-field
        label: Require Field
      - value: skip-field
        label: Skip Field Validation
      - value: require-value-range
        label: Require Value in Range
      - value: require-approval
        label: Require Approval

  - name: targetField
    type: string
    label: Target Field
    description: The taxon path this rule applies to
    required: true

  - name: condition
    type: string
    label: Condition Expression
    description: Optional condition for when rule applies

  - name: errorMessage
    type: string
    label: Error Message
    description: Message shown when validation fails

  - name: severity
    type: select
    label: Severity
    options:
      - value: error
        label: Error (blocks processing)
      - value: warning
        label: Warning (allows override)
      - value: info
        label: Info (notification only)
    default: error

Step 3: Create Knowledge Items

High-Value Invoice Rules

# Require manager approval for high-value invoices
title: Require Manager Approval
description: High-value invoices must have manager approval
knowledgeItemType: validation-rule
active: true
properties:
  ruleType: require-approval
  targetField: "approval/manager_signature"
  errorMessage: "Invoices over $10,000 require manager approval"
  severity: error

# Require cost center for high-value invoices
title: Require Cost Center
description: High-value invoices must specify cost center
knowledgeItemType: validation-rule
active: true
properties:
  ruleType: require-field
  targetField: "accounting/cost_center"
  errorMessage: "Cost center is required for invoices over $10,000"
  severity: error

International Vendor Rules

# Require tax documentation for international vendors
title: Require International Tax Documentation
description: International vendors require W-8BEN or equivalent
knowledgeItemType: validation-rule
active: true
properties:
  ruleType: require-field
  targetField: "vendor/tax_documentation_type"
  errorMessage: "International vendors require tax documentation (W-8BEN, W-8BEN-E, etc.)"
  severity: error

# Require wire transfer details for international
title: Require Wire Transfer Details
description: International payments require wire transfer information
knowledgeItemType: validation-rule
active: true
properties:
  ruleType: require-field
  targetField: "payment/wire_transfer_info"
  errorMessage: "Wire transfer details required for international vendors"
  severity: warning

Rush Order Rules

# Skip optional fields for rush orders
title: Skip Optional Field Validation
description: Rush orders can skip optional documentation
knowledgeItemType: validation-rule
active: true
properties:
  ruleType: skip-field
  targetField: "documentation/supporting_quotes"
  condition: "processing.priority == 'rush'"
  severity: info

Step 4: Create Knowledge Sets

High-Value Invoice Set

name: High-Value Invoice Validation
description: Additional validation for invoices over $10,000
status: ACTIVE

features:
  - featureTypeSlug: invoice-value-tier
    properties:
      tier: "high"

items:
  - itemSlug: require-manager-approval
  - itemSlug: require-cost-center

International Vendor Set

name: International Vendor Validation
description: Validation rules for international vendors
status: ACTIVE

features:
  - featureTypeSlug: vendor-location
    properties:
      locationType: "international"

items:
  - itemSlug: require-international-tax-documentation
  - itemSlug: require-wire-transfer-details

Rush Order Set

name: Rush Order Processing
description: Relaxed validation for rush orders
status: ACTIVE

features:
  - featureTypeSlug: processing-priority
    properties:
      priority: "rush"

items:
  - itemSlug: skip-optional-field-validation

Combining Multiple Features

Knowledge Sets can require multiple features. For example, high-value international invoices might need extra scrutiny:

name: High-Value International Invoice Validation
description: Enhanced validation for high-value international invoices
status: ACTIVE

# Both features must be present
features:
  - featureTypeSlug: invoice-value-tier
    properties:
      tier: "high"
  - featureTypeSlug: vendor-location
    properties:
      locationType: "international"

items:
  - itemSlug: require-manager-approval
  - itemSlug: require-international-tax-documentation
  - itemSlug: require-compliance-review  # Additional item for this combination

How Validation Works at Runtime

Viewing Validation Results

When validation rules are applied:

1. Passed validations - Document proceeds to next step
2. Failed validations (error) - Document is flagged with exceptions
3. Failed validations (warning) - Document can proceed with manual override
4. Informational - Notifications logged but processing continues

View applied knowledge and validation results in:

• Document details panel
• Exceptions list
• Workflow search (filter by validation status)

Best Practices

1. Use Appropriate Severity Levels

• Error: Critical business rules that must be met
• Warning: Important but can be overridden with justification
• Info: Nice-to-have or informational checks

2. Write Clear Error Messages

# Good
errorMessage: "Invoices over $10,000 require manager approval. Please upload signed approval form."

# Too vague
errorMessage: "Validation failed"

3. Document Your Rules

Use the description field to explain the business reason:

title: Require Tax Documentation
description: |
  IRS requires W-8BEN or W-8BEN-E for payments to non-US vendors.
  This ensures compliance with tax withholding requirements.
  Reference: IRS Publication 515

4. Test with Pending Review Status

Create Knowledge Sets with status: PENDING_REVIEW first to test without affecting production:

name: New Validation Rule (Testing)
status: PENDING_REVIEW  # Won't apply until activated

Next Steps

• Knowledge Feature Types - Full reference
• Knowledge Item Types - Full reference
• Customizing Extraction - Another common use case
• Knowledge and Agents - Automate rule discovery