Validation and Conditional Formatting - Kodexa Developer Portal

Validation rules and conditional formats are configured on data elements in a Data Definition. In configuration, those elements are stored under taxons. At runtime Kodexa applies those rules to the matching data objects and data attributes in each document. Use validation rules when the document data must satisfy a business rule. Use conditional formatting when reviewers need a visual cue while reviewing data. Both use the same formula language.

You do not add validationRules or conditionalFormats directly to a stored data object or data attribute. You add them to the Data Definition element that models that object or attribute. Kodexa evaluates the rule wherever that element appears in document data.

Where Rules Live

Rules can be attached at two levels:

Level	Attach to	Use for
Data attribute	A field element such as `invoice_number`, `due_date`, or `total_amount`	Required fields, field-level ranges, confidence checks, and conditional formatting on a form control
Data object	A group element such as `invoice`, `vendor`, or `line_items`	Cross-field checks where the rule describes the whole object

Attribute-level rules are the most common. They bind cleanly to a field in the review UI and can create exceptions against a specific data attribute. Object-level rules are useful when the business rule is about the row or section rather than a single field. For example, an invoice object can validate that subtotal + tax_amount matches total_amount.

Attribute-level rule

taxons:
  - name: invoice
    group: true
    children:
      - name: invoice_number
        label: Invoice Number
        taxonType: STRING
        validationRules:
          - name: Invoice number required
            ruleFormula: "!isblank({invoice_number})"
            messageFormula: '"Invoice number is required"'
            exceptionId: INVOICE_NUMBER_REQUIRED
            overridable: false

Object-level rule

taxons:
  - name: invoice
    group: true
    validationRules:
      - name: Invoice total matches components
        ruleFormula: |
          abs({total_amount} - (
            ifnull({subtotal}, 0) +
            ifnull({tax_amount}, 0) +
            ifnull({shipping_amount}, 0)
          )) < 0.01
        messageFormula: |
          concat(
            "Invoice total does not match the calculated total. Total: ",
            {total_amount}
          )
        exceptionId: INVOICE_TOTAL_MISMATCH
        overridable: true
    children:
      - name: subtotal
        taxonType: CURRENCY
      - name: tax_amount
        taxonType: CURRENCY
      - name: shipping_amount
        taxonType: CURRENCY
      - name: total_amount
        taxonType: CURRENCY

Validation Rules

Validation rules are stored in the validationRules array on a taxon. Each rule evaluates a formula. If the formula returns truthy, the data passes. If it returns falsy or errors, Kodexa treats the rule as failed.

validationRules:
  - id: due-date-after-invoice-date
    name: Due date after invoice date
    description: The payment due date must not be earlier than the invoice date.
    disabled: false
    conditional: true
    conditionalFormula: "!isblank({due_date}) && !isblank({invoice_date})"
    ruleFormula: "isafterdate({due_date}, {invoice_date}) || {due_date} = {invoice_date}"
    messageFormula: '"Due date must be on or after the invoice date"'
    detailFormula: |
      concat("Invoice date: ", {invoice_date}, ". Due date: ", {due_date}, ".")
    exceptionId: DUE_DATE_BEFORE_INVOICE_DATE
    supportArticleId: "9117988"
    overridable: false

Rule Fields

Field	Type	Required	Behavior
`id`	string	No	Stable rule identifier in metadata. Use one when configuration is managed in Git.
`name`	string	Recommended	Human-readable rule name shown in tooling and useful for derived exception keys.
`description`	string	No	Explains why the rule exists.
`disabled`	boolean	No	When `true`, Kodexa skips the rule.
`conditional`	boolean	No	When `true`, Kodexa evaluates `conditionalFormula` before the rule.
`conditionalFormula`	formula string	Required when `conditional` is `true`	If the formula is falsy or errors, Kodexa skips `ruleFormula`.
`ruleFormula`	formula string	Yes	Must evaluate truthy for the data to pass. Empty formulas are skipped.
`messageFormula`	formula string	Recommended	Builds the message for the exception when the rule fails.
`detailFormula`	formula string	No	Builds additional details for the exception.
`exceptionId`	string	Recommended	Stable exception type. If omitted, Kodexa derives a key from the taxon path and rule name.
`supportArticleId`	string	No	Help article ID attached to the resulting exception.
`overridable`	boolean	No	Controls whether a reviewer can override the exception. Defaults to not overridable when omitted.

Evaluation Flow

Kodexa finds the taxon for the changed data object or data attribute.
Disabled rules are skipped.
If conditional is true and conditionalFormula is present, Kodexa evaluates the condition.
If the condition is truthy, Kodexa evaluates ruleFormula.
Truthy results pass. Falsy results fail.
Formula errors are treated as failed validation and marked as evaluation errors so authors can diagnose bad rules.
Failing rules create or reopen data exceptions. Passing rules close matching open exceptions.

Validation formulas are reactive. When a formula references {subtotal}, {tax_amount}, or another attribute, Kodexa tracks that dependency and re-evaluates the affected rule when the referenced value changes.

Required Fields

Use isblank for required field checks. Missing references resolve to null, so isblank handles missing, null, empty-string, and empty-list values.

validationRules:
  - name: Vendor name required
    ruleFormula: "!isblank({vendor_name})"
    messageFormula: '"Vendor name is required"'
    exceptionId: VENDOR_NAME_REQUIRED
    overridable: false

Conditional Rules

Set conditional: true when a rule should apply only for some records.

validationRules:
  - name: PO number required for purchase-order invoices
    conditional: true
    conditionalFormula: "{invoice_type} = 'Purchase Order'"
    ruleFormula: "!isblank({purchase_order_number})"
    messageFormula: '"Purchase order number is required for PO invoices"'
    exceptionId: PO_NUMBER_REQUIRED
    overridable: false

If conditional is omitted or false, Kodexa evaluates ruleFormula regardless of conditionalFormula.

Cross-Field Rules

Attach cross-field rules to the field that should receive the exception, or to the group data element when the rule describes the full object.

validationRules:
  - name: Line total matches quantity times unit price
    conditional: true
    conditionalFormula: |
      !isblank({quantity}) && !isblank({unit_price}) && !isblank({line_total})
    ruleFormula: "abs({line_total} - ({quantity} * {unit_price})) < 0.01"
    messageFormula: |
      concat("Line total should be ", {quantity} * {unit_price}, " but was ", {line_total})
    exceptionId: LINE_TOTAL_MISMATCH
    overridable: true

Repeating Groups

When a formula references a child path that has multiple data objects, Kodexa returns an array of values. Math functions such as sum, average, min, and max can work across those arrays.

validationRules:
  - name: Invoice total equals line item total
    ruleFormula: "abs({total_amount} - sum({line_items/line_total})) < 0.01"
    messageFormula: |
      concat(
        "Invoice total ",
        {total_amount},
        " does not match line item total ",
        sum({line_items/line_total})
      )
    exceptionId: INVOICE_LINES_DO_NOT_SUM
    overridable: true

Formula Errors

Formula errors are configuration problems. For example, an unknown function, invalid syntax, or unsupported comparison can cause the rule to fail with evaluationErrored.

Avoid

ruleFormula: "NOT_EMPTY({invoice_number})"

Use

ruleFormula: "!isblank({invoice_number})"

The formula language is not SQL, JavaScript, or Excel. Use && and || for logic, = for equality, ! for not, and built-in functions such as isblank, ifnull, datemath, and contains.

Conditional Formatting

Conditional formats are stored in the conditionalFormats array on a taxon. Each format has:

Field	Type	Required	Behavior
`type`	string	Yes	Formatter type consumed by the review UI.
`condition`	formula string	Yes	Formula that activates the format when truthy.
`properties`	object	No	Formatter-specific properties, usually `color` or `icon`.

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
      color: "#D97706"

Supported Formatter Types

Type	Properties	Result
`backgroundColor`	`color`	Applies a background color to the attribute control.
`textColor`	`color`	Applies a text color to the attribute control.
`outlineColor`	`color`	Applies a colored outline around the attribute control.
`icon`	`icon`, `color`	Displays a review icon for the attribute.

Conditional formatting is attribute-oriented. Add conditionalFormats to the field taxon whose control should be styled.

Attribute styling

taxons:
  - name: invoice
    group: true
    children:
      - name: total_amount
        label: Total Amount
        taxonType: CURRENCY
        conditionalFormats:
          - type: backgroundColor
            condition: "{total_amount} > 10000"
            properties:
              color: "#FEF3C7"
          - type: icon
            condition: "{total_amount} > 10000"
            properties:
              icon: alert-circle-outline
              color: "#92400E"

Older examples may use formula, backgroundColor, textColor, or icon at the top level of a conditional format. The current Kodexa document runtime evaluates condition and returns active { type, properties } records, so new configuration should use the canonical shape shown above.

How Conditional Formats Recalculate

Kodexa builds a dependency graph from every condition. When any referenced value changes, the affected conditional formats are evaluated for that data object.

A truthy condition activates the format.
A falsy condition deactivates the format.
An empty condition is skipped.
A condition that errors is treated as inactive.
Kodexa caches active/inactive state and emits conditional format change events only when the state changes.

Formula Language

Validation rules and conditional formats use Kodexa’s KEXL formula language. The same syntax is used by formula data elements and other Data Definition features.

Literals

123
123.45
"Invoice total is required"
'PAID'
true
false
null
[1, 2, 3]

Strings can be single-quoted or double-quoted. Use backslash escapes such as \", \', \n, and \t, or double the quote character inside the same quote style.

Attribute References

Use curly braces to read values from the current data object or related data objects.

{invoice_number}              // Attribute on the current data object
{line_items/line_total}       // Child data object path, often returns an array
{../invoice_number}           // Attribute on the parent data object
{../../customer_name}         // Attribute two levels up
{./status}                    // Explicit self-relative attribute reference

References are case-insensitive when matching existing attributes. The formula service also understands data element externalName mappings, so generated data can use external names without changing the underlying element names.

Operators

Operator	Use
`+`, `-`, `*`, `/`	Arithmetic
`^`	Power
`&`	String concatenation
`=`	Equality
`!=`	Inequality
`<`, `<=`, `>`, `>=`	Ordered comparison
`&&`	Logical and, short-circuits
`\|\|`	Logical or, short-circuits
`!`	Logical not
`[]`	Array index access
`()`	Grouping

({subtotal} + {tax_amount}) = {total_amount}
!isblank({invoice_number}) && {total_amount} > 0
concat("Invoice ", {invoice_number}) & " is ready"

Use = for equality. Do not use ==. Use && and ||; uppercase AND and OR are not formula operators.

Truthy and Falsy Values

Kodexa uses truthiness when deciding whether a validation passes or a conditional format is active.

Value	Truthiness
`true`	truthy
`false`	falsy
Non-zero number	truthy
Zero	falsy
Non-empty string	truthy
Empty string	falsy
Non-empty array	truthy
Empty array	falsy
`null`	falsy

Function Reference

Function names are case-insensitive, but examples should use lower-case names for consistency.

Function	Example	Notes
`sum`	`sum({line_items/line_total})`	Adds numeric values. Arrays are summed.
`average`	`average({scores/value})`	Mean of numeric values. Returns zero when there are no numeric values.
`min`	`min({line_items/amount})`	Lowest numeric value.
`max`	`max({line_items/amount})`	Highest numeric value.
`abs`	`abs({expected} - {actual})`	Absolute value. Arrays are summed first.
`ceil`	`ceil({amount})`	Round toward positive infinity.
`floor`	`floor({amount})`	Round toward negative infinity.
`round`	`round({amount})`	Round to nearest integer.
`stddeviation`	`stddeviation(1, 2, 3)`	Standard deviation.
`decimalplaces`	`decimalplaces({amount}, 2, "round_half_up")`	Decimal rounding. Default mode is floor.
`concat`	`concat("PO ", {purchase_order_number})`	Converts arguments to strings and joins them.
`substring`	`substring({code}, 0, 3)`	String slice using start and end indexes.
`lowercase`	`lowercase({vendor_name})`	Returns lower-case string values.
`uppercase`	`uppercase({vendor_name})`	Returns upper-case string values.
`trim`	`trim({vendor_name})`	Trims whitespace.
`replace`	`replace({phone}, "-", "")`	Replaces all occurrences.
`split`	`split({csv_value}, ",")`	Returns an array.
`strlen`	`strlen({invoice_number})`	Length of string value.
`length`	`length({line_items/line_total})`	Length of string, array, map, or object representation.
`len`	`len({line_items/line_total})`	Alias for `length`.
`if`	`if({amount} > 0, "debit", "credit")`	Conditional result. Arguments are evaluated before the function runs.
`ifnull`	`ifnull({tax_amount}, 0)`	Returns fallback for `null` or empty arrays.
`sumifs`	`sumifs({amounts}, {types}, "freight")`	Sums values where criteria match.
`countifs`	`countifs({statuses}, {statuses}, "open")`	Counts values where criteria match.
`isnull`	`isnull({field})`	True for null or empty arrays.
`isblank`	`isblank({field})`	True for null, empty arrays, or whitespace-only strings.
`contains`	`contains({description}, "freight")`	Substring check.
`startswith`	`startswith({code}, "INV")`	Prefix check.
`endswith`	`endswith({code}, "-US")`	Suffix check.
`datemath`	`datemath({invoice_date}, "days", 30)`	Adds days, weeks, months, or years. `datemath("today")` returns today’s date.
`isdate`	`isdate({invoice_date})`	True when the value can be parsed as a date.
`isbeforedate`	`isbeforedate({invoice_date}, {due_date})`	Date comparison, ignoring time.
`isafterdate`	`isafterdate({due_date}, {invoice_date})`	Date comparison, ignoring time.
`daysbetween`	`daysbetween({invoice_date}, {due_date})`	Full days between two dates.
`weeksbetween`	`weeksbetween({start_date}, {end_date})`	Full weeks between two dates.
`monthsbetween`	`monthsbetween({start_date}, {end_date})`	Month difference between two dates.
`validatedate`	`validatedate({invoice_date})`	True when the date parses.
`formatdate`	`formatdate({invoice_date}, "yyyy-MM-dd")`	Formats a date using Java date-pattern syntax.
`regex`	`regex({invoice_number}, "^[A-Z0-9-]+$")`	Go regular expression match.
`matches`	`matches({invoice_number}, "^[A-Z0-9-]+$")`	Alias for `regex`.
`confidence`	`confidence("invoice_number")`	Reads confidence for an attribute on the current data object.
`count`	`count(1, 2, 3)`	Counts function arguments.
`selectioncontains`	`selectioncontains({available_codes}, {code})`	Checks string values or `{ label, value }` option objects.
`getvalue`	`getvalue("../invoice_number")`	Resolves a path supplied as a string.
`servicebridgecall`	`servicebridgecall("VendorLookup", "lookup", "name", {vendor_name})`	Calls a configured Service Bridge when available in the runtime.

Eager and Short-Circuit Evaluation

Function arguments are evaluated before the function runs. That means if does not protect an invalid branch from being evaluated.

Avoid

if({denominator} = 0, 0, {numerator} / {denominator})

Use logical operators when you need short-circuit behavior.

Use

{denominator} != 0 && ({numerator} / {denominator}) > 10

Common Formula Patterns

Required value

!isblank({invoice_number})

Optional date ordering

isblank({due_date}) || isblank({invoice_date}) || isafterdate({due_date}, {invoice_date}) || {due_date} = {invoice_date}

Numeric tolerance

abs({expected_total} - {actual_total}) < 0.01

Date window

!isblank({due_date}) &&
isafterdate({due_date}, datemath("today", "days", -1)) &&
isbeforedate({due_date}, datemath("today", "days", 31))

Selection-like text

{status} = "Approved" || {status} = "Approved with Conditions"

Dynamic path

getvalue("../" & {field_name}) = "Complete"

Recommended Authoring Pattern

Put field-level validation and formatting on the field taxon.
Put object-level validation on the group data element.
Use stable exceptionId values for customer-facing exceptions.
Use conditional: true only when the rule has a real gating condition.
Write formulas with explicit braces around every data reference.
Prefer isblank, ifnull, abs, datemath, and date comparison functions over hand-rolled string checks.
Keep conditional formatting visual and non-blocking; use validation rules for business conditions that must be resolved.

Data Definitions Guide

Start with the overall data definition model.

Event-Based Scripting

Use scripts when a rule needs side effects or procedural logic.

Selection Option Formulas

Compute dropdown options dynamically from document context.

Formula Reference

See the broader formula guide and examples.

​Where Rules Live

​Validation Rules

​Rule Fields

​Evaluation Flow

​Required Fields

​Conditional Rules

​Cross-Field Rules

​Repeating Groups

​Formula Errors

​Conditional Formatting

​Supported Formatter Types

​How Conditional Formats Recalculate

​Formula Language

​Literals

​Attribute References

​Operators

​Truthy and Falsy Values

​Function Reference

​Eager and Short-Circuit Evaluation

​Common Formula Patterns

​Recommended Authoring Pattern

​Related

Data Definitions Guide

Event-Based Scripting

Selection Option Formulas

Formula Reference

Where Rules Live

Validation Rules

Rule Fields

Evaluation Flow

Required Fields

Conditional Rules

Cross-Field Rules

Repeating Groups

Formula Errors

Conditional Formatting

Supported Formatter Types

How Conditional Formats Recalculate

Formula Language

Literals

Attribute References

Operators

Truthy and Falsy Values

Function Reference

Eager and Short-Circuit Evaluation

Common Formula Patterns

Recommended Authoring Pattern

Related