Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developer.kodexa.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Data definitions in Kodexa provide the structure and rules for extracting, validating, and processing information from documents. They define what data to extract, how to validate it, and how to present it to users.

​
What Are Data Definitions?

Data definitions are the blueprints for your document processing workflows. They specify:
  • Structure: What data elements exist and how they relate
  • Types: What kind of data each field contains (text, numbers, dates, etc.)
  • Sources: Where data comes from (document content, metadata, calculations, review)
  • Validation: Business rules and data quality checks
  • Behavior: Formulas, selection options, event scripts, and validation cascades that run when data changes

Data Definition Structure

Data elements, groups, sources, and extraction behavior

Event-Based Scripting

Reactive JavaScript scripts that run when modeled data changes

Formulas

Calculation logic for derived and computed fields

Validation and Formatting

Business rules, exceptions, and reviewer-facing visual cues

​
Core Concepts

​
Data Structure

Data definitions are hierarchical structures of data elements that define what to extract from documents. In configuration and API payloads, those elements are still stored under the taxons field. Example use cases:
  • Invoice data extraction (vendor, line items, totals)
  • Contract metadata (parties, dates, terms)
  • Form processing (applicant info, answers, signatures)

Data Definition Structure

Learn how data elements, groups, value sources, and extraction behavior fit together

​
Data Types

Kodexa supports rich data types for accurate extraction and validation:
  • STRING - Text of any length
  • NUMBER - Numeric values
  • BOOLEAN - True/false values
  • DATE - Calendar dates
  • DATE_TIME - Dates with timestamps

​
Data Sources

Define where each data element gets its value:
Extract directly from document content using AI/ML models
valuePath: VALUE_OR_ALL_CONTENT
semanticDefinition: "Extract the invoice total amount"
Pull from document properties and system fields
valuePath: METADATA
metadataValue: FILENAME
Calculate from other fields
valuePath: FORMULA
semanticDefinition: "quantity * unit_price"
Fields populated during human review
valuePath: REVIEW
userEditable: true

​
Common Patterns

​
Invoice Processing

Extract structured data from invoices: 
taxons:
  - name: invoice_number
    label: Invoice Number
    taxonType: STRING

  - name: invoice_date
    label: Invoice Date
    taxonType: DATE

  - name: vendor
    label: Vendor
    group: true
    children:
      - name: name
      - name: address
      - name: tax_id

  - name: line_items
    label: Line Items
    group: true
    children:
      - name: description
      - name: quantity
      - name: unit_price
      - name: total
        valuePath: FORMULA
        semanticDefinition: "quantity * unit_price"

  - name: total_amount
    label: Total Amount
    taxonType: CURRENCY

​
Contract Metadata

Capture key contract information: 
taxons:
  - name: contract_type
    label: Contract Type
    taxonType: SELECTION
    selectionOptions:
      - label: "Service Agreement"
      - label: "Purchase Order"
      - label: "NDA"

  - name: parties
    group: true
    children:
      - name: party_a
      - name: party_b

  - name: key_terms
    group: true
    children:
      - name: effective_date
        taxonType: DATE
      - name: term_length
      - name: termination_notice

​
Form Data

Process form submissions: 
taxons:
  - name: applicant
    group: true
    children:
      - name: full_name
      - name: email
        taxonType: EMAIL_ADDRESS
      - name: phone
        taxonType: PHONE_NUMBER

  - name: responses
    group: true
    children:
      - name: question_1
      - name: question_2
      - name: agree_to_terms
        taxonType: BOOLEAN

​
Validation and Quality

​
Validation Rules

Define business rules to ensure data quality: 
validationRules:
  - name: "Required field check"
    ruleFormula: "!isblank({invoice_number})"
    messageFormula: '"Invoice number is required"'
    overridable: false

  - name: "Date logic check"
    conditional: true
    conditionalFormula: "!isblank({due_date}) && !isblank({invoice_date})"
    ruleFormula: "isafterdate({due_date}, {invoice_date}) || {due_date} = {invoice_date}"
    messageFormula: '"Due date must be after invoice date"'
    overridable: false

  - name: "Total verification"
    ruleFormula: "abs({total_amount} - sum({line_items/total})) < 0.01"
    messageFormula: '"Total mismatch detected"'
    overridable: true

Validation and Conditional Formatting

Learn the exact validationRules schema, conditional formatting schema, formula language, and runtime behavior.

​
Conditional Formatting

Apply visual cues based on data values: 
conditionalFormats:
  - type: backgroundColor
    condition: "isbeforedate({due_date}, datemath('today')) && {status} != 'PAID'"
    properties:
      color: "#FEE2E2"

  - type: icon
    condition: "{total_amount} > 10000"
    properties:
      icon: alert-circle-outline
      color: "#92400E"

​
Best Practices

​
Design Principles

Begin with core fields and add complexity as needed. Don’t over-engineer initial data definitions.Start with:
  • Essential fields only
  • Basic data types
  • Simple validation
Add later:
  • Computed fields
  • Complex validations
  • Conditional formatting
Write clear, specific extraction prompts:Good:
semanticDefinition: |
  The vendor's legal business name as it appears at the top of the invoice.
  Look near 'Bill To', 'From', or 'Vendor' labels.
Avoid:
semanticDefinition: "vendor name"  # Too vague
Use groups to:
  • Organize related fields logically
  • Handle repeating structures (line items, signatories)
  • Improve UI presentation
Single instance groups: Organizational containers
- name: vendor
  group: true
  children: [name, address, tax_id]
Repeating groups: Collections
- name: line_items
  group: true
  children: [description, quantity, price]
Critical validations (non-overridable):
  • Required fields
  • Data type constraints
  • Business logic rules
Quality checks (overridable):
  • Unusual values
  • Formatting issues
  • Threshold warnings

​
Naming Conventions

Use consistent naming across your data definitions: 
name: vendor_name         # Snake case
name: invoice_date        # Descriptive, unambiguous
name: line_items          # Plural for groups

​
Getting Started

1

Understand Your Documents

Analyze the documents you’ll process:
  • What data needs to be extracted?
  • What’s the document structure?
  • What validations are needed?
2

Design Your Data Definition

Sketch out the data structure:
  • List all required fields
  • Group related fields
  • Identify repeating sections
3

Configure Data Elements

For each field, define:
  • Data type
  • Value source
  • Semantic definition
  • Validation rules
4

Test and Iterate

Process sample documents:
  • Verify extraction accuracy
  • Refine semantic definitions
  • Adjust validation rules

​
Learn More

Data Definition Structure

Data elements, groups, value sources, and configuration options

Formula Reference

Built-in functions for calculations and validations

Validation and Formatting

Complete guide to validation rules, conditional formats, and formula behavior

Event-Based Scripting

Add reactive JavaScript behavior to the data model

API Documentation

Programmatic access to data definition management

​
Examples

Invoice Data Definition

Complete invoice extraction example

Contract Data Definition

Contract metadata extraction example

Form Data Definition

Form data processing example

Purchase Order Data Definition

Purchase order extraction example