Data Definition

Kodexa data-definition authoring

A data-definition ("taxonomy" is an accepted alias) is a document's extraction schema: a tree of taxons saying what to capture, how to compute it, how to validate it and how to colour it. Org-scoped, stored at <metadata-dir>/data-definitions/<slug>.yaml, referenced as data-definition://<orgSlug>/<slug> or taxonomy://<orgSlug>/<slug> — both resolve against kdxa_taxonomies to /api/data-definitions/{id}. See references/schema.md (fields), references/formulas.md (KEXL) and references/examples.md.

The envelope — three keys, or kdx apply never reaches the server

type: dataDefinition        # REQUIRED. aliases: data-definition, dataDefinition, taxonomy, taxonomies
slug: invoice-extraction    # REQUIRED, unique within the org
orgSlug: acme-corp          # REQUIRED
name: Invoice Extraction
version: 1.0.0
description: Structured data captured from supplier invoices.
taxonomyType: CONTENT       # CONTENT | PROCESSING | MODEL — free-form string, only these are read
enabled: true
externalDataTaxonomyRefs: []
taxons: []

type and orgSlug may instead come from --type / --org-slug, but slug must be in the file. CONTENT is what data grids, tree views and taxon pickers look for; PROCESSING/MODEL mark a taxonomy non-content and hide it from labelling — there is no MODULE. And a taxonomy has no top-level validationRules: or conditionalFormats: — unknown top-level keys are ignored on decode, so a rules array written there is accepted with a 2xx and then silently vanishes. Rules and formats live on taxons only: put a cross-field rule on whichever taxon should own the exception and navigate with {../Sibling} / {Group/Child}.

Naming — four fields, four subsystems

name, externalName and valuePath are the required taxon properties; label is not.

The editor derives externalName from label by stripping non-alphanumerics ("Line Total" → "LineTotal"). Set it on every taxon — a formula naming a taxon that does not exist never errors.

A taxon

- name: invoice_number            # required
  externalName: InvoiceNumber     # required — the formula key
  label: Invoice Number
  taxonType: STRING               # 14 wire values, 12 in the editor (references/schema.md)
  valuePath: VALUE_OR_ALL_CONTENT # required — 8 wire values, 4 in the editor
  description: "Human documentation. The extraction model NEVER sees this."
  semanticDefinition: "The AI-facing extraction instruction — this IS the prompt."
  typeFeatures: { expected: true }   # adds the property to the extraction schema's `required` list

Under valuePath: FORMULA, semanticDefinition holds the formula text itself; it is skipped entirely for METADATA, DATA_PATH, FORMULA and REVIEW.

Groups and repeating groups

Hang everything under one root group. A data object exists per group taxon, and a rule or formula runs against the data object at its own taxon's path — so a bare {Sibling} reference only resolves between taxons that share a group. Give the definition one group: true root.

- name: line_items
  externalName: LineItems
  label: Line Items
  valuePath: VALUE_OR_ALL_CONTENT
  group: true                     # container — holds children, stores no value of its own
  typeFeatures: { cardinality: multiple }   # single | multiple — ALWAYS set this on a group
  children: [...]

typeFeatures.cardinality decides whether a group produces one object or an array. Three call sites disagree about what an unset value means, so state it explicitly on every group; multiValue is the leaf equivalent and its unset default also differs by layer, so state that too.

Never write cardinality: {min: 1, max: 100}. Taxon-level cardinality is a string; an object there aborts the whole decode with cannot unmarshal object into ... TaxonCardinality, so the request is rejected and nothing is written. Avoid taxon-level cardinality altogether — the API types it ONCE_PER_DOCUMENT | MULTIPLE_PER_DOCUMENT | ONCE_PER_SEGMENT | MULTIPLE_PER_SEGMENT, which is a different vocabulary from the single/multiple one that actually drives shape.

additionContexts (record-boundary hints) are read only when typeFeatures.chunkingStrategy contains record and a context of the matching type is present — without both the block is dead configuration, no warning. The four *_MARKER values are regexes, only RECORD_DEFINITION takes prose (references/schema.md).

Formulas (KEXL) — the shape that parses

One language across ruleFormula, conditionalFormula, messageFormula, detailFormula, conditionalFormats[].condition, selectionOptionFormula and semanticDefinition-under-FORMULA.

# ✅
ruleFormula: "!isblank({InvoiceNumber})"
ruleFormula: "abs({TotalAmount} - ({Subtotal} + ifnull({TaxAmount}, 0))) < 0.01"
conditionalFormula: "!isblank({DueDate}) && !isblank({InvoiceDate})"
messageFormula: '"Invoice number is required"'   # KEXL string literal inside YAML quotes
# ❌ parse or evaluation failures
ruleFormula: "NOT_EMPTY(invoice_number)"             # no such function; bare identifiers don't resolve
ruleFormula: "line_items.quantity > 0"               # "." outside "./" is a parse error
conditionalFormula: "NOT_EMPTY(a) AND NOT_EMPTY(b)"  # AND/and/OR/or are not operators — use && and ||
ruleFormula: "{Status} == 'PAID'"                    # "==" is a parse error — equality is a single "="

• References are {Braces} with / separators, resolved against the externalName chain: {InvoiceNumber}, {LineItems/LineTotal}, {./Sibling}, {../Parent}, {/Absolute/Path}. Equality is a single =; !=, <, >, <=, >= are normal; logic is && / || / !.
• NOT_EMPTY, IS_EMPTY, COALESCE, TODAY, DATE_ADD, REGEX_MATCH, IN, ALL_VALUES, UNIQUE and NOT do not exist. The registry is fixed — isBlank, ifNull, regex, dateMath, count, sum, … matched case-insensitively. Full list and a translation: references/formulas.md.
• A reference that resolves to nothing does not error — it comes back null or an empty list, so a misspelled externalName quietly makes sum(...) return 0 and isblank(...) true. An unknown function does error, but only per document at review time, as a data exception reading Validation rule configuration error. Neither is caught at apply time.

To check a group has rows, reference the group itself from its parent group — the parent still has a data object when the child has no rows. !isblank({LineItems}) there works because {LineItems} resolves to the list of child data objects and isblank is true for an empty list; {LineItems/SomeChild} resolves against those children, so it is not an emptiness test.

Conditional formats — nested, or silently inert

conditionalFormats:                                # type: backgroundColor | outlineColor | textColor | icon
  - { type: backgroundColor, condition: "{TotalAmount} > 10000", properties: { color: "#FEF3C7" } }
  - { type: icon, condition: "{TotalAmount} > 50000", properties: { icon: alert-circle, color: "#B91C1C" } }

The runtime reads only type, condition and properties. A flat entry ({name, formula, backgroundColor, textColor, fontWeight, icon}) decodes without error, the colour/weight keys are then dropped on ingest and formula is stored but never read — nothing renders, nothing complains. An empty condition is skipped; formats paint cells, so use leaf taxons.

Selection options — the model is constrained to the LABEL

For taxonType: SELECTION, the extraction schema's enum is the set of enabled option labels. id is an opaque row key and is never the stored value; add value: only when the UI must store something other than the label. Write the label exactly as it should appear in extracted data. Each option's description and lexicalRelations are injected into the extraction prompt (only SYNONYM and ANTONYM get a gloss) — use them for the wordings real documents use, one entry per term, because a comma-packed value reads as a single phrase. Dynamic dropdowns: references/schema.md.

Declared but inert

Persisted and round-tripped, sometimes editable in the UI, but nothing in the platform reads them.

Common mistakes

Verifying

kdx validate -f <file> checks the file against the API's create schema without sending anything — but that schema nests the taxonomy body one level down, so the taxons are never type-checked (they surface as unrecognized-key warnings). Validate confirms the envelope, not the tree. Anything inside taxons — the cardinality shape above most of all — is caught only when kdx apply -f <file> posts it and the server refuses the body; formulas are checked at neither point. kdx dataclasses <file> generates Python dataclasses from the taxonomy, and GET /api/data-definitions/{id}/json-schema returns a draft-07 schema of the enabled taxons keyed by externalName ("Download JSON Schema").

Related skills: kdx-cli (apply envelope, kdx get/kdx run), project-resource (binding a definition into a project), data-form (forms bind to taxon paths and consume selection options), activity-plan (SCRIPT steps write into taxon paths — see its references/step-types.md), service-bridge (serviceBridgeCall), knowledge-system (runtime overrides of names and prompts).