Data Definitions Guide - Kodexa Developer Portal

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:

Basic Types
Specialized Types
Complex Types

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:

Document Extraction

Extract directly from document content using AI/ML models

valuePath: VALUE_OR_ALL_CONTENT
semanticDefinition: "Extract the invoice total amount"

Metadata

Pull from document properties and system fields

valuePath: METADATA
metadataValue: FILENAME

Formulas

Calculate from other fields

valuePath: FORMULA
semanticDefinition: "quantity * unit_price"

Review

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

Start Simple, Iterate

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

Use Semantic Definitions Well

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

Organize with Groups

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]

Validate Strategically

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

label: Vendor Name        # Title case
label: Invoice Date       # Human-readable
label: Line Items         # Matches business terminology

externalName: vendorName  # Camel case
externalName: invoiceDate # Consistent with API conventions

Getting Started

Understand Your Documents

Analyze the documents you’ll process:

What data needs to be extracted?
What’s the document structure?
What validations are needed?

Design Your Data Definition

Sketch out the data structure:

List all required fields
Group related fields
Identify repeating sections

Configure Data Elements

For each field, define:

Data type
Value source
Semantic definition
Validation rules

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

​Overview

​What Are Data Definitions?

Data Definition Structure

Event-Based Scripting

Formulas

Validation and Formatting

​Core Concepts

​Data Structure

Data Definition Structure

​Data Types

​Data Sources

​Common Patterns

​Invoice Processing

​Contract Metadata

​Form Data

​Validation and Quality

​Validation Rules

Validation and Conditional Formatting

​Conditional Formatting

​Best Practices

​Design Principles

​Naming Conventions

​Getting Started

​Learn More

Data Definition Structure

Formula Reference

Validation and Formatting

Event-Based Scripting

API Documentation

​Examples

Invoice Data Definition

Contract Data Definition

Form Data Definition

Purchase Order Data Definition

Overview

What Are Data Definitions?

Core Concepts

Data Structure

Data Types

Data Sources

Common Patterns

Invoice Processing

Contract Metadata

Form Data

Validation and Quality

Validation Rules

Conditional Formatting

Best Practices

Design Principles

Naming Conventions

Getting Started

Learn More

Examples