Skip to main content

Extending the Data Model

ZeyOS has a fixed database schema with standard entities — contacts, accounts, transactions, tasks, tickets, and more — each with predefined fields. But applications often need to store additional data specific to their use case: a CRM might need a "lead score" on contacts, or a billing app might need a "payment terms" field on accounts.

ExtData solves this by providing a key-value overlay that augments any entity with custom fields — without altering the underlying schema. Each application can extend entity types independently, without conflicting with other applications or the core data model.

How it works​

ExtData fields are stored as key-value pairs associated with an entity record. Each field has a string key and a string value. You can read, write, and delete ExtData fields using the extdata namespace, or include them inline when using db:set for entity operations.

Reading custom fields​

Use extdata:get to retrieve custom field values from an entity:

XML
<extdata:get var="data" entity="contacts" id="$contact_id">
    <extdata:field>company</extdata:field>
    <extdata:field>competitor</extdata:field>
</extdata:get>
<output>Company: $data.company</output>

If no <extdata:field> children are specified, all ExtData fields are returned.

Writing custom fields​

Use extdata:set to write custom field values. Supports both inline data and variable-based data:

XML
<!-- Inline data -->
<extdata:set entity="contacts" id="$id">
    <extdata:data field="company">Microsoft</extdata:data>
    <extdata:data field="competitor">Apple</extdata:data>
</extdata:set>

<!-- From variable -->
<extdata:set entity="contacts" id="$id" var_data="data_array"/>

Read-modify-write pattern​

XML
<extdata:get var="obj" entity="contacts" id="$id">
    <extdata:field>company</extdata:field>
</extdata:get>

<if value1="$obj.company" func="=" value2="Microsoft">
    <set var="obj.competitor">Apple</set>
</if>

<extdata:set entity="contacts" id="$id" var_data="obj"/>

Removing custom fields​

Use extdata:unset to remove fields:

XML
<extdata:unset entity="contacts" id="$id">
    <extdata:field>company</extdata:field>
</extdata:unset>

Using ExtData with db:set​

When creating or updating entities with db:set, you can include ExtData fields inline alongside standard entity fields. This lets you set core data and custom fields in a single operation:

XML
<db:set entity="contacts" var="newId">
    <db:data field="firstname">John</db:data>
    <db:data field="lastname">Smith</db:data>
    <extdata:data field="department">Engineering</extdata:data>
    <extdata:data field="employee_id">EMP-0042</extdata:data>
    <tags:name>Employee</tags:name>
</db:set>

When to use ExtData vs. standard fields​

  • Use standard fields (via db:data) for data that maps to ZeyOS's built-in entity schema — firstname, lastname, email, status, etc.
  • Use ExtData for application-specific data that doesn't exist in the core schema — user preferences, computed values, integration IDs from external systems, custom categorizations, or any domain-specific attribute your application needs.

ExtData fields are scoped to the application. Multiple apps can each define their own ExtData fields on the same entity type without interfering with each other.