Data Definition Structure

Overview

Data definitions are the foundation of data extraction in Kodexa. They define the hierarchical structure of data elements you want to extract from documents, along with their types, validation rules, and extraction logic.

What is a Data Definition?

A Data Definition is a hierarchical structure of data elements. In configuration and API payloads, those elements are represented as taxons. A Data Definition defines:

What data to extract from documents
Where the data comes from (document content, metadata, formulas)
How to validate and format the data
What type of data it is (string, date, currency, etc.)

Key Concepts

Data Definition

Top-level container defining the complete data structure for extraction

Data Element

Individual field or group within a Data Definition

Data Group

Organizational container that groups related data elements without storing data itself

Value Path

Defines where the data element gets its value from (document, metadata, formula, etc.)

Top-Level Configuration

Every data definition has these core properties:

slug: invoice-data
name: Invoice Data Extraction
description: Extract structured data from invoices
taxonomyType: CONTENT
enabled: true
taxons:
  - name: vendor_information
    label: Vendor Information
    # ... data element configuration

Data Definition Properties

Property	Type	Default	Description
`slug`	string	-	Unique identifier for the data definition
`name`	string	-	Display name
`description`	string	-	Description of the data definition’s purpose
`taxonomyType`	enum	`CONTENT`	Type of data definition (typically CONTENT)
`enabled`	boolean	`true`	Whether the data definition is active
`externalDataTaxonomyRefs`	string[]	`[]`	References to external data definitions
`taxons`	Taxon[]	`[]`	Array of root-level data elements

Data Element Configuration

Data elements are the individual fields and groups within a Data Definition. In configuration, each one is a taxon with extensive options organized into several categories.

Basic Properties

Every data element requires these fundamental properties:

id: "auto-generated-uuid"
name: vendor_name
label: Vendor Name
description: The name of the vendor or supplier
enabled: true
color: "#4F46E5"

name

string

required

Internal identifier (alphanumeric, hyphens, underscores only)

label

string

required

Human-readable display name

description

string

Detailed explanation of what this data element represents

enabled

boolean

default:"true"

Whether this data element is active (disabled elements cascade to children)

color

string

Hex color code for UI display (auto-generated if not specified)

generateName

boolean

default:"true"

Auto-generate the internal name from the label

externalName

string

Name used when publishing to external systems (auto-generated from label if not specified)

Data Source (Value Path)

The valuePath determines where the data element gets its value from:

Document (VALUE_OR_ALL_CONTENT)

Extracts data directly from document content using AI/ML models or pattern matching.When to use: Standard document extraction (invoices, contracts, forms)Configuration:

valuePath: VALUE_OR_ALL_CONTENT
semanticDefinition: "Extract the vendor's business name as it appears on the invoice"

Features:

Uses semantic definition as extraction prompt
Can leverage document structure and layout
Supports AI-assisted extraction

Metadata (METADATA)

Pulls data from document metadata (filename, creation date, owner, etc.).When to use: Document properties, system fields, audit trailConfiguration:

valuePath: METADATA
metadataValue: FILENAME  # or CREATED_DATETIME, OWNER_NAME, etc.

Available metadata values:

FILENAME - Document filename
TRANSACTION_UUID - Unique transaction identifier
CREATED_DATETIME - Document creation timestamp
DOCUMENT_LABELS - Applied labels
OWNER_NAME - Document owner
DOCUMENT_STATUS - Processing status
PAGE_NUMBER - Current page number

Formula (FORMULA)

Calculates values using formulas that reference other data elements.When to use: Computed fields, calculations, aggregationsConfiguration:

valuePath: FORMULA
semanticDefinition: |
  sum({line_items/amount})

Features:

Reference other data elements with {field_name} or {group/field_name}
Built-in functions such as sum, average, if, isblank, and datemath
Conditional logic support

Review (REVIEW)

Generates review templates using Jinja2 templating.When to use: Human review interfaces, validation checklistsConfiguration:

valuePath: REVIEW
semanticDefinition: |
  ## Review Checklist

  - [ ] Vendor name matches PO: {{ vendor_name }}
  - [ ] Total amount is correct: {{ total_amount }}
  - [ ] All line items present: {{ line_items|length }} items

Derived (DERIVED)

Placeholder for derived values (less common, use FORMULA instead).

Data Types

The taxonType defines how the data should be treated and validated:

taxonType: STRING
typeFeatures:
  longText: true           # Multi-line text field
  maxTextRows: 10          # Maximum rows for display
  markdown: true           # Enable markdown formatting
  expected: true           # Field is expected to be present
  stringExtract: '\d'      # Keep only matching characters (regex)
  stringReplace: '[-\s]'   # Remove matching characters (regex)

Use for: Names, addresses, descriptions, any text content

Use stringExtract and stringReplace to automatically clean extracted values. See String Filters below.

taxonType: NUMBER
typeFeatures:
  truncateDecimal: true    # Round to fixed decimal places
  decimalPlaces: 2         # Number of decimal places

Use for: Quantities, counts, measurements

taxonType: CURRENCY
typeFeatures:
  preferTwoDecimalPlaces: true  # Assume last 2 digits are decimal (1234 → 12.34)

Use for: Prices, totals, monetary amounts

taxonType: DATE
typeFeatures:
  normalizeDate: true              # Normalize for display
  normalizeDateInExport: true      # Normalize in exports
  dateFormat: "yyyy-MM-dd"         # Target format

Use for: Invoice dates, due dates, any date without time

taxonType: DATE_TIME
typeFeatures:
  normalizeDate: true
  dateFormat: "yyyy-MM-dd HH:mm:ss"

Use for: Timestamps, creation dates with time

SELECTION data elements present users with a dropdown of predefined options and guide AI extraction toward valid categorical values.

Basic Example

taxonType: SELECTION
selectionOptions:
  - label: "Net 30"
    id: "net_30"
    description: "Payment due in 30 days"
  - label: "Net 60"
    id: "net_60"
    description: "Payment due in 60 days"

Use for: Dropdown selections, categorical data, classification

Selection Option Properties

Each item in selectionOptions supports these properties:

Property	Type	Description
`label`	string	Required. Display text shown to the user in the dropdown
`id`	string	Unique identifier for the option (auto-generated if omitted)
`value`	string	The value stored when this option is selected. Defaults to `label` if empty. Use this to separate display text from stored codes (e.g., label “Net 30” with value “NET_30”)
`description`	string	Description text shown alongside the option
`hint`	string	Additional help text displayed with the option
`hintMarkdown`	boolean	When `true`, renders the `hint` as Markdown instead of plain text
`disabled`	string	Set to `"true"` to disable the option. Disabled options are excluded from AI extraction requests but remain visible (struck through) in the UI. Useful for deprecating options without breaking existing data
`isConditional`	boolean	Enables conditional visibility for this option
`conditionalFormula`	string	Formula evaluated per data object to determine if this option appears. Only used when `isConditional` is `true`
`lexicalRelations`	array	Semantic relationships that help AI/ML models understand option equivalences. See Lexical Relations below

Value vs Label

When value is set, the UI displays the label but stores the value. This is useful when you need human-readable display text but machine-friendly stored values:

selectionOptions:
  - label: "United States Dollar"
    value: "USD"
    id: "currency_usd"
  - label: "Euro"
    value: "EUR"
    id: "currency_eur"

Hints

Hints provide contextual help for individual options. Enable Markdown rendering for rich formatting:

selectionOptions:
  - label: "Net 30"
    id: "net_30"
    hint: "Standard payment terms — **30 calendar days** from invoice date"
    hintMarkdown: true
  - label: "Due on Receipt"
    id: "due_receipt"
    hint: "Payment expected immediately upon receipt of invoice"

Disabled Options

Disabled options are excluded from AI extraction prompts (so the model won’t extract them from new documents) but remain visible in the UI for historical data:

selectionOptions:
  - label: "Net 30"
    id: "net_30"
    disabled: ""          # Active — included in AI requests
  - label: "Net 15"
    id: "net_15"
    disabled: "true"      # Deprecated — excluded from AI requests, shown struck-through

The disabled field is a string, not a boolean. Use "true" to disable and "" (empty string) or omit for enabled.

Conditional Options

Show or hide individual options based on the current data object’s context using isConditional and conditionalFormula:

selectionOptions:
  - label: "Standard"
    id: "priority_standard"
  - label: "Rush"
    id: "priority_rush"
    isConditional: true
    conditionalFormula: "{total_amount} > 10000"
  - label: "Emergency"
    id: "priority_emergency"
    isConditional: true
    conditionalFormula: "{total_amount} > 50000 && {is_critical} = true"

The conditionalFormula is evaluated against the current data object at runtime. Options where the formula evaluates to false are hidden from the dropdown. Options without isConditional always appear.

Lexical Relations on Selection Options

Lexical relations help AI models understand synonyms and related terms for each option, improving extraction accuracy when documents use varied terminology:

selectionOptions:
  - label: "Net 30"
    id: "net_30"
    description: "Payment due in 30 days"
    lexicalRelations:
      - type: SYNONYM
        value: "30 days, thirty days, N30"
      - type: SIMILAR_TO
        value: "monthly payment"
        weight: 0.7
  - label: "Due on Receipt"
    id: "due_receipt"
    lexicalRelations:
      - type: SYNONYM
        value: "immediate payment, payable on receipt, COD"
      - type: ANTONYM
        value: "deferred payment"

Supported relation types: SYNONYM, ANTONYM, HYPERNYM (more general), HYPONYM (more specific), MERONYM (part-of), HOLONYM (whole-of), ENTAILMENT, SIMILAR_TO, OTHEREach relation has:

type — The relationship type from the list above
value — The related term(s). Can be comma-separated for multiple terms
weight — Optional confidence/importance weight (0.0–1.0)

Dynamic Options with Formulas

Instead of a static list, you can compute selection options dynamically using a JavaScript formula. Enable this on the data element:

taxonType: SELECTION
useSelectionOptionFormula: true
selectionOptionFormula: |
  serviceBridgeCall("myorg/reference-data", "get-currencies", {
    country: getAttribute("country_code")
  })

The formula is evaluated by the Goja scripting runtime and must return an array of {label, value} objects or plain strings. Options re-evaluate automatically when referenced attributes change, and the results are persisted on the data object so they survive page reloads.

For the full guide on dynamic selection options — including service bridge integration, grid child formulas, dependency tracking, and troubleshooting — see Selection Option Formulas.

Complete Example

- name: payment_terms
  label: Payment Terms
  taxonType: SELECTION
  semanticDefinition: "The payment terms specified on the invoice"
  selectionOptions:
    - label: "Net 10"
      value: "NET_10"
      id: "terms_net10"
      description: "Payment due in 10 days"
      lexicalRelations:
        - type: SYNONYM
          value: "10 days, N10"
    - label: "Net 30"
      value: "NET_30"
      id: "terms_net30"
      description: "Payment due in 30 days"
      hint: "Most common payment term for B2B invoices"
      lexicalRelations:
        - type: SYNONYM
          value: "30 days, N30, thirty days"
    - label: "Net 60"
      value: "NET_60"
      id: "terms_net60"
      description: "Payment due in 60 days"
      isConditional: true
      conditionalFormula: "total_amount > 10000"
      lexicalRelations:
        - type: SYNONYM
          value: "60 days, N60"
    - label: "Due on Receipt"
      value: "DUE_ON_RECEIPT"
      id: "terms_receipt"
      description: "Payment expected immediately"
      lexicalRelations:
        - type: SYNONYM
          value: "immediate, COD, cash on delivery, payable on receipt"
    - label: "2/10 Net 30"
      value: "2_10_NET_30"
      id: "terms_2_10_net30"
      description: "2% discount if paid within 10 days, otherwise net 30"
      hint: "Early payment discount — **2% off** if paid within 10 days"
      hintMarkdown: true
      disabled: "true"

taxonType: BOOLEAN

Use for: Yes/no fields, flags, checkboxes

Additional specialized types:

URL - Website addresses
EMAIL_ADDRESS - Email addresses
PHONE_NUMBER - Phone numbers
PERCENTAGE - Percentage values
SECTION - Visual grouping (no data storage)

Data Groups and Hierarchies

Groups organize related data elements and can represent repeating structures:

name: line_items
label: Line Items
group: true                    # This is a group, not a value
children:
  - name: description
    label: Description
    taxonType: STRING

  - name: quantity
    label: Quantity
    taxonType: NUMBER

  - name: unit_price
    label: Unit Price
    taxonType: CURRENCY

  - name: total
    label: Total
    taxonType: CURRENCY
    valuePath: FORMULA
    semanticDefinition: "quantity * unit_price"

Group Configuration

group

boolean

default:"false"

Mark as a group (container for other data elements)

children

Taxon[]

Array of child data elements nested under this group

cardinality

object

Define how many instances of this group can exist:

cardinality:
  min: 1      # Minimum required instances
  max: 100    # Maximum allowed instances

naturalKeys

object[]

Define unique identifiers for group instances:

naturalKeys:
  - taxonRef: "invoice_number"
  - taxonRef: "line_number"

eventSubscriptions

TaxonEventSubscription[]

Attach reactive JavaScript scripts to a group data element. Event subscriptions can derive values, enforce business rules, call Service Bridges, create data exceptions, or emit follow-up events when modeled data changes.

eventSubscriptions:
  - name: derive-total
    on: "changed:dataAttribute:(quantity|unit_price)"
    script: |
      if (!currentObject) return;
      var qty = currentObject.getFirstAttributeValue("quantity");
      var price = currentObject.getFirstAttributeValue("unit_price");
      if (qty && price) {
        currentObject.setAttribute("line_total", qty * price);
      }

For the full runtime guide, including the JavaScript objects available to scripts, see Event-Based Scripting.

Validation Rules

Define business rules and data quality checks on the data element they apply to:

validationRules:
  - name: "Total matches sum of line items"
    description: "Ensure calculated total matches the invoice total"
    disabled: false
    conditional: false
    ruleFormula: |
      abs({total_amount} - sum({line_items/total})) < 0.01
    messageFormula: |
      concat(
        "Total mismatch: Invoice shows ",
        {total_amount},
        " but line items sum to ",
        sum({line_items/total})
      )
    detailFormula: |
      "Check line item totals and invoice-level charges."
    overridable: true
    exceptionId: TOTAL_MISMATCH
    supportArticleId: "9117988"

  - name: "Due date after invoice date"
    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

Validation Rule Properties

Property	Type	Description
`name`	string	Rule name
`description`	string	Detailed explanation
`disabled`	boolean	Temporarily disable this rule
`conditional`	boolean	Only apply if condition is true
`conditionalFormula`	string	Formula determining if rule applies
`ruleFormula`	string	Formula that must be true (false = validation failure)
`messageFormula`	string	Formula generating the error message
`detailFormula`	string	Formula generating additional details
`overridable`	boolean	Can users override this validation?
`exceptionId`	string	Unique exception identifier
`supportArticleId`	string	Link to help documentation

Validation and Conditional Formatting

Read the complete guide for rule placement, exception lifecycle, conditional formatting schema, and the formula language.

Conditional Formatting

Apply visual formatting based on data values:

conditionalFormats:
  - type: backgroundColor
    condition: "isbeforedate({due_date}, datemath('today')) && {status} != 'PAID'"
    properties:
      color: "#FEE2E2"

  - type: textColor
    condition: "isbeforedate({due_date}, datemath('today')) && {status} != 'PAID'"
    properties:
      color: "#991B1B"

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

Classification Features

Help AI/ML models understand and classify content:

Semantic Definition

Provides guidance for AI extraction:

semanticDefinition: |
  The vendor's legal business name as registered with tax authorities.
  Look for names near "Bill To", "Vendor", or "From" sections.
  Should be a proper business name, not an individual's name.

Best practices:

Be specific about what to look for
Describe location hints
Clarify edge cases
Provide examples if helpful

Additional Context

Helps with record-based chunking and classification:

additionContexts:
  - type: RECORD_DEFINITION
    context: |
      Each line item represents a product or service being billed.
      Line items typically appear in a table format.

  - type: RECORD_START_MARKER
    context: "Item #"

  - type: RECORD_END_MARKER
    context: "Subtotal"

Context types:

RECORD_DEFINITION - Describes the record structure
RECORD_START_MARKER - Text indicating record start
RECORD_END_MARKER - Text indicating record end
RECORD_SECTION_STARTER_MARKER - Section start marker
RECORD_SECTION_END_MARKER - Section end marker

Lexical Relations

Synonyms and antonyms for embedding-based classification:

lexicalRelations:
  - type: SYNONYM
    value: "Supplier, Provider, Seller, Merchant"

  - type: ANTONYM
    value: "Customer, Buyer, Client"

Use for:

Improving classification accuracy
Handling terminology variations
Training embedding models

Advanced Options

Chunking Strategy

chunkingStrategy controls how a document is divided into segments before extraction. It is set on group taxons (typically the root taxon) and is a spatial-only selector — it applies to spatial documents (and legacy callers that do not specify a document mixin). Setting it on a non-spatial document is a misconfiguration that the extraction resolvers reject.

name: invoice
taxonType: GROUP
typeFeatures:
  chunkingStrategy: document     # Treat the whole document as one chunk

Valid values:

Value	Effect
`document`	The whole document becomes a single chunk
`page`	One chunk per page
`firstNPages`	Chunk from the first N pages only
`classifiedContent`	Chunk from content classified for this taxon
`pageClassifiedContent`	Page-level chunking over classified content
`groupClassifiedContent`	Group-level chunking over classified content
`record`	Record-based chunking (see Additional Context markers)

Defaults for spatial / legacy group taxons: If a group taxon does not explicitly set chunkingStrategy, one is filled in automatically (existing values are never overridden):

If the planner has marked the group as non-embedded (its own chunk context), it defaults to classifiedContent.
Otherwise — including an unplanned or unconfigured taxonomy — it defaults to document, so the whole document is extracted as a single chunk.

Because these defaults apply only to group taxons on spatial (or legacy) documents, a typical spatial taxonomy extracts without needing to set chunkingStrategy at all. Set it explicitly when you want a different segmentation than the default.

If no enabled root taxon declares a chunkingStrategy and none is filled in by default (for example, a spatial taxonomy whose root taxons are not group taxons, so the automatic document default never applies), the extraction produces zero chunks and no data. This is a valid outcome for a blank taxonomy, so it is not an error — the extraction logs a warning instead. See Extraction produces no data if you expected output.

Display Configuration

Control how fields appear in the UI:

typeFeatures:
  overrideWidth: true
  displayWidth: 300            # Width in pixels
  expected: true               # Mark as required field

String Filters

Automatically clean extracted values using regex patterns. Extract keeps only matching characters, Replace removes matching characters. If both are set, extract runs first. The original value is preserved separately.

typeFeatures:
  stringExtract: '\d'            # Keep only digits
  stringReplace: '[^a-zA-Z0-9]' # Remove non-alphanumeric characters

Common Patterns
Examples

Pattern	Effect
`\d`	Keep digits only (use with `stringExtract`)
`[a-zA-Z]`	Keep letters only (use with `stringExtract`)
`[-\s]`	Strip dashes and spaces (use with `stringReplace`)
`[^a-zA-Z0-9]`	Strip all non-alphanumeric (use with `stringReplace`)
`[^a-zA-Z0-9 ]`	Strip special characters but keep spaces (use with `stringReplace`)

Pro number cleanup — remove special characters:

name: pronumber
taxonType: STRING
typeFeatures:
  stringReplace: '[^a-zA-Z0-9 ]'

Phone number — digits only:

name: phone
taxonType: STRING
typeFeatures:
  stringExtract: '\d'

ID field — strip dashes and spaces:

name: tracking_id
taxonType: STRING
typeFeatures:
  stringReplace: '[-\s.]'

Combined — extract digits then strip leading zeros:

name: account_number
taxonType: STRING
typeFeatures:
  stringExtract: '\d'
  stringReplace: '^0+'

User Interaction

multiValue: true               # Allow multiple values
userEditable: true             # User can edit in forms
notUserLabelled: false         # Show in labeling interface
nullable: true                 # Allow null values
nullValue: "N/A"              # Display text for null

Common Patterns

Invoice Extraction

Complete example of a typical invoice data definition:

slug: invoice-extraction
name: Invoice Data Extraction
taxonomyType: CONTENT
enabled: true
taxons:
  # Header Information
  - name: invoice_number
    label: Invoice Number
    taxonType: STRING
    valuePath: VALUE_OR_ALL_CONTENT
    semanticDefinition: "The unique invoice number, typically at the top right"
    validationRules:
      - name: "Invoice number required"
        ruleFormula: "!isblank({invoice_number})"
        messageFormula: '"Invoice number is required"'
        overridable: false

  - name: invoice_date
    label: Invoice Date
    taxonType: DATE
    valuePath: VALUE_OR_ALL_CONTENT
    semanticDefinition: "The date the invoice was issued"
    typeFeatures:
      normalizeDate: true
      dateFormat: "yyyy-MM-dd"

  - name: due_date
    label: Due Date
    taxonType: DATE
    valuePath: VALUE_OR_ALL_CONTENT
    semanticDefinition: "The payment due date"

  # Vendor Information Group
  - name: vendor
    label: Vendor
    group: true
    children:
      - name: name
        label: Vendor Name
        taxonType: STRING
        valuePath: VALUE_OR_ALL_CONTENT
        semanticDefinition: "The vendor's business name"

      - name: address
        label: Address
        taxonType: STRING
        valuePath: VALUE_OR_ALL_CONTENT
        typeFeatures:
          longText: true

      - name: tax_id
        label: Tax ID
        taxonType: STRING
        valuePath: VALUE_OR_ALL_CONTENT

  # Line Items (Repeating Group)
  - name: line_items
    label: Line Items
    group: true
    children:
      - name: description
        label: Description
        taxonType: STRING

      - name: quantity
        label: Quantity
        taxonType: NUMBER

      - name: unit_price
        label: Unit Price
        taxonType: CURRENCY

      - name: line_total
        label: Line Total
        taxonType: CURRENCY
        valuePath: FORMULA
        semanticDefinition: "{quantity} * {unit_price}"

  # Totals
  - name: subtotal
    label: Subtotal
    taxonType: CURRENCY
    valuePath: FORMULA
    semanticDefinition: "sum({line_items/line_total})"

  - name: tax_amount
    label: Tax Amount
    taxonType: CURRENCY
    valuePath: VALUE_OR_ALL_CONTENT

  - name: total_amount
    label: Total Amount
    taxonType: CURRENCY
    valuePath: VALUE_OR_ALL_CONTENT
    validationRules:
      - name: "Total calculation check"
        ruleFormula: "abs({total_amount} - ({subtotal} + ifnull({tax_amount}, 0))) < 0.01"
        messageFormula: '"Total amount mismatch"'
        overridable: true

Contract Data Extraction

slug: contract-extraction
name: Contract Data Extraction
taxons:
  - name: contract_metadata
    label: Contract Metadata
    group: true
    children:
      - name: contract_number
        label: Contract Number
        taxonType: STRING

      - name: contract_type
        label: Contract Type
        taxonType: SELECTION
        selectionOptions:
          - label: "Service Agreement"
            id: "service"
          - label: "Purchase Agreement"
            id: "purchase"
          - label: "NDA"
            id: "nda"
          - label: "License Agreement"
            id: "license"

  - name: parties
    label: Parties
    group: true
    children:
      - name: party_a
        label: Party A
        taxonType: STRING

      - name: party_b
        label: Party B
        taxonType: STRING

  - name: key_terms
    label: Key Terms
    group: true
    children:
      - name: effective_date
        label: Effective Date
        taxonType: DATE

      - name: term_length
        label: Term Length
        taxonType: STRING
        semanticDefinition: "Duration of the contract (e.g., '12 months', '2 years')"

      - name: auto_renewal
        label: Auto Renewal
        taxonType: BOOLEAN
        semanticDefinition: "Does the contract automatically renew?"

      - name: termination_notice
        label: Termination Notice Period
        taxonType: STRING
        semanticDefinition: "Required notice period for termination (e.g., '30 days')"

  - name: financial_terms
    label: Financial Terms
    group: true
    children:
      - name: total_value
        label: Total Contract Value
        taxonType: CURRENCY

      - name: payment_terms
        label: Payment Terms
        taxonType: STRING
        semanticDefinition: "Payment schedule and terms (e.g., 'Net 30', 'Monthly in advance')"

Best Practices

Naming Conventions

name: vendor_name           # Snake case for internal names
label: Vendor Name          # Title case for display
externalName: vendorName    # Camel case for APIs

name: VendorName            # Don't use capitals in internal names
label: vendor_name          # Don't use technical names for display

Semantic Definitions

Write semantic definitions as if explaining to a human what to look for. Be specific about:

What the field represents
Where it typically appears
How to identify it
Edge cases to consider

Good example:

semanticDefinition: |
  The total amount due on the invoice, including all taxes and fees.
  Look for labels like "Total", "Amount Due", "Balance Due", or "Total Amount".
  This should be the final bottom-line number, not a subtotal.
  If multiple totals exist (e.g., by currency), extract the primary total.

Avoid:

semanticDefinition: "The total"  # Too vague

Group Structures

# Good: Line items are a repeating group
- name: line_items
  label: Line Items
  group: true
  children:
    - name: description
    - name: quantity
    - name: price

# Good: Vendor info as an organizational group
- name: vendor
  label: Vendor Information
  group: true
  children:
    - name: name
    - name: address
    - name: tax_id

Validation Strategy

Start Simple: Begin with basic “not empty” validations
Add Business Rules: Implement domain-specific validations
Make Critical Rules Non-Overridable: Block processing if essential data is wrong
Allow Overrides for Quality Checks: Let users override formatting or minor issues

validationRules:
  # Critical: Don't allow override
  - name: "Invoice number required"
    ruleFormula: "!isblank({invoice_number})"
    overridable: false

  # Quality check: Allow override
  - name: "Total seems high"
    ruleFormula: "{total_amount} < 100000"
    messageFormula: '"Invoice total exceeds $100,000 - please verify"'
    overridable: true

Formula Usage

Simple Calculations

semanticDefinition: "{quantity} * {unit_price}"

Aggregations

semanticDefinition: "sum({line_items/total})"

Conditional Logic

semanticDefinition: |
  if({total_amount} > 10000, "Requires Approval", "Auto-Approve")

Date Calculations

semanticDefinition: "datemath({invoice_date}, 'days', 30)"

Troubleshooting

Common Issues

Data element not appearing in UI

Possible causes:

enabled: false is set
Parent data element is disabled (disabling cascades to children)
notUserLabelled: true for labeling interfaces

Solution: Check enabled status up the hierarchy

Extraction not working

Check:

Is valuePath correct for your use case?
Is semanticDefinition clear and specific?
Are you using the right taxonType?
Is the model trained for this document type?

Formula errors

Common mistakes:

Referencing data elements that don’t exist
Syntax errors in formula
Circular references

Test: Use formula builder to validate syntax

Validation not triggering

Check:

Is validation rule disabled: false?
Does conditionalFormula evaluate to true?
Is ruleFormula returning the expected boolean?

Next Steps

Data Types Reference

Reference guide for all supported data types

Formula Reference

Complete formula function reference

Selection Option Formulas

Compute dropdown options dynamically using JavaScript and service bridges

Event-Based Scripting

Attach reactive JavaScript behavior to group data elements

Scripting Reference

Complete API reference for Kodexa JavaScript scripting

Validation and Formatting

Common validation rule and conditional formatting patterns

​Overview

​What is a Data Definition?

​Key Concepts

Data Definition

Data Element

Data Group

Value Path