Data Objects & Attributes

Data objects and data attributes provide a structured data layer within KDDB documents. Data objects represent extracted entities (e.g., an invoice line item, a person, an address), while data attributes store the individual fields and values associated with those entities.

Overview

The data layer is separate from the content node tree and designed for storing extraction results:

Data Objects: Entities with parent-child relationships and taxonomy references
Data Attributes: Typed fields attached to data objects (string, decimal, date, boolean)
Confidence Scores: Each attribute can have an extraction confidence score
Taxonomy Integration: Objects and attributes can reference taxonomy definitions

Data Objects

Creating Data Objects

from kodexa_document import Document
from kodexa_document.accessors import DataObjectInput

with Document() as doc:
    root = doc.create_node("document", "Invoice #12345")
    doc.content_node = root

    # Create a root data object
    invoice = doc.data_objects.create(DataObjectInput(
        path="/invoice"
    ))
    print(f"Created data object: {invoice}")

    # Create child data objects
    line_item_1 = doc.data_objects.create(DataObjectInput(
        parent_id=invoice['id'],
        path="/invoice/line-item"
    ))

    line_item_2 = doc.data_objects.create(DataObjectInput(
        parent_id=invoice['id'],
        path="/invoice/line-item"
    ))

import { Kodexa } from '@kodexa-ai/document-wasm-ts';

async function createDataObjects() {
  await Kodexa.init();
  const doc = await Kodexa.createDocument();

  try {
    // Create a root data object
    const invoice = await doc.dataObjects.create({
      path: '/invoice'
    });
    console.log(`Created data object: ${invoice.id}`);

    // Create child data objects
    const lineItem1 = await doc.dataObjects.create({
      parentId: invoice.id,
      path: '/invoice/line-item'
    });

    const lineItem2 = await doc.dataObjects.create({
      parentId: invoice.id,
      path: '/invoice/line-item'
    });
  } finally {
    doc.dispose();
  }
}

Retrieving Data Objects

with Document.from_kddb("processed.kddb") as doc:
    # Get all data objects
    all_objects = doc.data_objects.get_all()
    print(f"Total data objects: {len(all_objects)}")

    # Get root-level objects only
    roots = doc.data_objects.get_roots()

    # Get children of a specific object
    for root_obj in roots:
        children = doc.data_objects.get_children(root_obj['groupUuid'])
        print(f"Object {root_obj['path']} has {len(children)} children")

    # Get by UUID
    obj = doc.data_objects.get_by_uuid("some-uuid")

    # Get by group UUID
    group = doc.data_objects.get_by_group_uuid("group-uuid")

async function retrieveDataObjects() {
  await Kodexa.init();
  const doc = await Kodexa.fromBlob(kddbBlob);

  try {
    // Get all data objects
    const allObjects = await doc.dataObjects.getAll();
    console.log(`Total data objects: ${allObjects.length}`);

    // Get root-level objects only
    const roots = await doc.dataObjects.getRoots();

    // Get children of a specific object
    for (const rootObj of roots) {
      const children = await doc.dataObjects.getChildren(rootObj.id);
      console.log(`Object ${rootObj.path} has ${children.length} children`);
    }

    // Get by ID
    const obj = await doc.dataObjects.getByID(1);

    // Get by taxonomy reference
    const byTaxonomy = await doc.dataObjects.getByTaxonomyRef('acme/invoice:1.0.0');

    // Get by path
    const byPath = await doc.dataObjects.getByPath('/invoice/line-item');
  } finally {
    doc.dispose();
  }
}

Updating and Deleting Data Objects

with Document.from_kddb("processed.kddb") as doc:
    # Update a data object
    doc.data_objects.update("some-uuid", DataObjectInput(
        path="/invoice/updated-path"
    ))

    # Delete a data object
    doc.data_objects.delete("some-uuid")

async function modifyDataObjects() {
  await Kodexa.init();
  const doc = await Kodexa.fromBlob(kddbBlob);

  try {
    // Update a data object
    await doc.dataObjects.update(1, { path: '/invoice/updated-path' });

    // Delete a data object
    await doc.dataObjects.delete(1);

    // Move a data object to a new parent
    await doc.dataObjects.move(2, 5, '/new-parent/child');

    // Copy a data object (with attributes)
    await doc.dataObjects.copy(1, 5, '/new-parent/copied', true);
  } finally {
    doc.dispose();
  }
}

Data Attributes

Creating Data Attributes

from kodexa_document.accessors import DataAttributeInput

with Document() as doc:
    root = doc.create_node("document", "Invoice")
    doc.content_node = root

    # Create a data object first
    invoice = doc.data_objects.create(DataObjectInput(path="/invoice"))

    # Add string attribute
    doc.data_attributes.create(invoice['id'], DataAttributeInput(
        tag="vendor-name",
        string_value="Acme Corp",
        confidence=0.95,
        owner_uri="model://kodexa/invoice-extractor:1.0.0"
    ))

    # Add decimal attribute
    doc.data_attributes.create(invoice['id'], DataAttributeInput(
        tag="total-amount",
        decimal_value=1234.56,
        confidence=0.92
    ))

    # Add date attribute
    doc.data_attributes.create(invoice['id'], DataAttributeInput(
        tag="invoice-date",
        date_value="2024-01-15",
        confidence=0.98
    ))

    # Add boolean attribute
    doc.data_attributes.create(invoice['id'], DataAttributeInput(
        tag="is-paid",
        boolean_value=False,
        confidence=1.0
    ))

async function createDataAttributes() {
  await Kodexa.init();
  const doc = await Kodexa.createDocument();

  try {
    // Create a data object first
    const invoice = await doc.dataObjects.create({ path: '/invoice' });

    // Add string attribute
    await doc.dataAttributes.create(invoice.id, {
      tag: 'vendor-name',
      stringValue: 'Acme Corp',
      confidence: 0.95,
      ownerUri: 'model://kodexa/invoice-extractor:1.0.0'
    });

    // Add decimal attribute
    await doc.dataAttributes.create(invoice.id, {
      tag: 'total-amount',
      decimalValue: 1234.56,
      confidence: 0.92
    });

    // Add date attribute
    await doc.dataAttributes.create(invoice.id, {
      tag: 'invoice-date',
      dateValue: '2024-01-15',
      confidence: 0.98
    });

    // Add boolean attribute
    await doc.dataAttributes.create(invoice.id, {
      tag: 'is-paid',
      booleanValue: false,
      confidence: 1.0
    });
  } finally {
    doc.dispose();
  }
}

Retrieving Data Attributes

with Document.from_kddb("processed.kddb") as doc:
    # Get all data objects
    objects = doc.data_objects.get_all()

    for obj in objects:
        # Get attributes for a data object
        attrs = doc.data_attributes.get_for_data_object(obj['id'])

        for attr in attrs:
            print(f"  {attr['tag']}: {attr.get('stringValue') or attr.get('decimalValue')}")
            print(f"    Confidence: {attr.get('confidence')}")

    # Get a specific attribute by ID
    attr = doc.data_attributes.get_by_id(1)

async function retrieveDataAttributes() {
  await Kodexa.init();
  const doc = await Kodexa.fromBlob(kddbBlob);

  try {
    // Get all data objects
    const objects = await doc.dataObjects.getAll();

    for (const obj of objects) {
      // Get attributes for a data object
      const attrs = await doc.dataAttributes.getForDataObject(obj.id);

      for (const attr of attrs) {
        const value = doc.dataAttributes.getTypedValue(attr);
        console.log(`  ${attr.tag}: ${value}`);
        console.log(`    Confidence: ${attr.confidence}`);
      }
    }

    // Get by tag name
    const vendorAttrs = await doc.dataAttributes.getByTag('vendor-name');

    // Get by path
    const pathAttrs = await doc.dataAttributes.getByPath('/invoice/vendor-name');

    // Get a specific attribute by ID
    const attr = await doc.dataAttributes.getByID(1);
  } finally {
    doc.dispose();
  }
}

Updating Data Attributes

with Document.from_kddb("processed.kddb") as doc:
    # Update an attribute
    doc.data_attributes.update(1, DataAttributeInput(
        string_value="Updated Vendor Name",
        confidence=0.99
    ))

    # Delete an attribute
    doc.data_attributes.delete(1)

async function updateDataAttributes() {
  await Kodexa.init();
  const doc = await Kodexa.fromBlob(kddbBlob);

  try {
    // Update an attribute value
    await doc.dataAttributes.setValue(1, 'Updated Vendor Name');

    // Update confidence
    await doc.dataAttributes.setConfidence(1, 0.99);

    // Add a feature to an attribute
    await doc.dataAttributes.addFeature(1, 'source', 'manual-correction');

    // Delete an attribute
    await doc.dataAttributes.delete(1);
  } finally {
    doc.dispose();
  }
}

Batch Writes

Document.batch_transaction() queues data object and attribute operations and applies them in a single atomic call. Operations inside a transaction carry the same payload as the direct accessors: a created attribute persists its value, tag_id, data_features, confidence and timestamps, and formulas that depend on an attribute the transaction creates or updates are recalculated. See Transactions for the full API.

DataObjectInput Reference

Field	Python	TypeScript	Description
Parent	`parent_id`	`parentId`	ID of the parent data object
Taxonomy	`taxonomy_ref`	`taxonomyRef`	Reference to a taxonomy definition
Path	`path`	`path`	Hierarchical path identifier

DataAttributeInput Reference

Field	Python	TypeScript	Description
Tag	`tag`	`tag`	Tag name linking to the content node tag
Tag ID	`tag_id`	`tagId`	Direct tag ID reference
Value	`value`	`value`	Generic value
String Value	`string_value`	`stringValue`	String-typed value
Decimal Value	`decimal_value`	`decimalValue`	Numeric value
Date Value	`date_value`	`dateValue`	Date string value (see the accepted formats below)
Boolean Value	`boolean_value`	`booleanValue`	Boolean value
Confidence	`confidence`	`confidence`	Extraction confidence (0-1)
Type	`type_at_creation`	`typeAtCreation`	Type classification
Path	`path`	`path`	Hierarchical path identifier
Owner URI	`owner_uri`	`ownerUri`	Source identifier (e.g., model URI)
Data Features	`data_features`	`dataFeatures`	Additional metadata dictionary

Accepted date formats. dateValue is parsed flexibly, so you do not have to pre-format dates: RFC 3339 (2024-01-15T00:00:00Z), a date-time with no timezone (2024-01-15T15:04:05), a bare ISO date (2024-01-15), month-name forms (2026-Mar-01, 1-Jan-2025) and US numeric forms (04-30-2025, 1-2-2026) all resolve to a stored date. Numeric dash dates are read as month-day-year. A string that cannot be parsed leaves the attribute’s stored date unchanged rather than writing a wrong one.

Complete Example

from kodexa_document import Document
from kodexa_document.accessors import DataObjectInput, DataAttributeInput

def extract_invoice_data():
    with Document() as doc:
        root = doc.create_node("document", "Invoice #12345")
        doc.content_node = root

        # Create the invoice data object
        invoice = doc.data_objects.create(DataObjectInput(
            path="/invoice",
            taxonomy_ref="acme/invoice:1.0.0"
        ))

        # Add header attributes
        doc.data_attributes.create(invoice['id'], DataAttributeInput(
            tag="invoice-number",
            string_value="INV-2024-001",
            confidence=0.99
        ))
        doc.data_attributes.create(invoice['id'], DataAttributeInput(
            tag="vendor-name",
            string_value="Acme Corp",
            confidence=0.95
        ))
        doc.data_attributes.create(invoice['id'], DataAttributeInput(
            tag="invoice-date",
            date_value="2024-01-15",
            confidence=0.98
        ))

        # Create line items
        items = [
            ("Widget A", 100.00),
            ("Widget B", 250.00),
            ("Service Fee", 50.00)
        ]

        for desc, amount in items:
            line_item = doc.data_objects.create(DataObjectInput(
                parent_id=invoice['id'],
                path="/invoice/line-item"
            ))
            doc.data_attributes.create(line_item['id'], DataAttributeInput(
                tag="description",
                string_value=desc,
                confidence=0.92
            ))
            doc.data_attributes.create(line_item['id'], DataAttributeInput(
                tag="amount",
                decimal_value=amount,
                confidence=0.90
            ))

        # Add total
        doc.data_attributes.create(invoice['id'], DataAttributeInput(
            tag="total-amount",
            decimal_value=400.00,
            confidence=0.95
        ))

        # Query the results
        roots = doc.data_objects.get_roots()
        for obj in roots:
            attrs = doc.data_attributes.get_for_data_object(obj['id'])
            print(f"Data Object: {obj['path']}")
            for attr in attrs:
                print(f"  {attr['tag']}: {attr.get('stringValue') or attr.get('decimalValue')}")

        doc.save("extracted_invoice.kddb")

import { Kodexa } from '@kodexa-ai/document-wasm-ts';

async function extractInvoiceData() {
  await Kodexa.init();
  const doc = await Kodexa.createDocument();

  try {
    const root = await doc.createNode('document');
    await root.setContent('Invoice #12345');

    // Create the invoice data object
    const invoice = await doc.dataObjects.create({
      path: '/invoice',
      taxonomyRef: 'acme/invoice:1.0.0'
    });

    // Add header attributes
    await doc.dataAttributes.create(invoice.id, {
      tag: 'invoice-number',
      stringValue: 'INV-2024-001',
      confidence: 0.99
    });
    await doc.dataAttributes.create(invoice.id, {
      tag: 'vendor-name',
      stringValue: 'Acme Corp',
      confidence: 0.95
    });
    await doc.dataAttributes.create(invoice.id, {
      tag: 'invoice-date',
      dateValue: '2024-01-15',
      confidence: 0.98
    });

    // Create line items
    const items = [
      { desc: 'Widget A', amount: 100.00 },
      { desc: 'Widget B', amount: 250.00 },
      { desc: 'Service Fee', amount: 50.00 }
    ];

    for (const { desc, amount } of items) {
      const lineItem = await doc.dataObjects.create({
        parentId: invoice.id,
        path: '/invoice/line-item'
      });
      await doc.dataAttributes.create(lineItem.id, {
        tag: 'description',
        stringValue: desc,
        confidence: 0.92
      });
      await doc.dataAttributes.create(lineItem.id, {
        tag: 'amount',
        decimalValue: amount,
        confidence: 0.90
      });
    }

    // Add total
    await doc.dataAttributes.create(invoice.id, {
      tag: 'total-amount',
      decimalValue: 400.00,
      confidence: 0.95
    });

    // Query the results
    const roots = await doc.dataObjects.getRoots();
    for (const obj of roots) {
      const attrs = await doc.dataAttributes.getForDataObject(obj.id);
      console.log(`Data Object: ${obj.path}`);
      for (const attr of attrs) {
        const value = doc.dataAttributes.getTypedValue(attr);
        console.log(`  ${attr.tag}: ${value}`);
      }
    }

    const blob = await doc.toBlob();
    console.log('Document exported successfully');
  } finally {
    doc.dispose();
  }
}

Overview

Document Data

Document Structure

Structured Data

Change Management

Python SDK

Overview

Data Objects

Creating Data Objects

Retrieving Data Objects

Updating and Deleting Data Objects

Data Attributes

Creating Data Attributes

Retrieving Data Attributes

Updating Data Attributes

Batch Writes

DataObjectInput Reference

DataAttributeInput Reference

Complete Example

​Overview

​Data Objects

​Creating Data Objects

​Retrieving Data Objects

​Updating and Deleting Data Objects

​Data Attributes

​Creating Data Attributes

​Retrieving Data Attributes

​Updating Data Attributes

​Batch Writes

​DataObjectInput Reference

​DataAttributeInput Reference

​Complete Example

Overview

Data Objects

Creating Data Objects

Retrieving Data Objects

Updating and Deleting Data Objects

Data Attributes

Creating Data Attributes

Retrieving Data Attributes

Updating Data Attributes

Batch Writes

DataObjectInput Reference

DataAttributeInput Reference

Complete Example