DTRules
Documentation Menu

Entity Data Dictionary

The Entity Data Dictionary (EDD) defines the data model for your rules. It specifies what entities exist, what attributes they have, and how they relate to each other.

What is an Entity?

An entity is a data object in your rule system. Think of it like a class in object-oriented programming or a table in a database. Common examples:

  • Person - name, age, income
  • Application - status, submitted_date
  • Household - address, members
  • Benefit - type, amount

Defining Entities

Entities are defined in an Excel spreadsheet (*_edd.xls) with these columns:

Column Description
Entity Entity name (starts a new entity definition)
Attribute Attribute name
Type Data type (string, integer, decimal, boolean, date, entity, array)
Subtype For arrays, the element type
Default Default value
Input Whether it's input data (Y/N)
Comment Documentation

Data Types

Primitive Types

Type Description Example
string Text "John Doe"
integer Whole number 42
decimal Decimal number 123.45
boolean True/false true
date Date value 2024-01-15

Complex Types

Type Description Usage
entity Reference to another entity Type column has entity name
array List of values Subtype column has element type

Example EDD

Here's an example EDD for a simple eligibility system:

Entity Attribute Type Subtype Default
Person
name string
age integer 0
income decimal 0
citizen boolean false
birth_date date
Household
address string
head Person
members array Person
Application
household Household
status string "pending"
eligible boolean false
benefit_amount decimal 0

Entity Relationships

One-to-One

An attribute whose type is another entity:

// Application has one Household
household: Household

// Accessing in rules:
application.household.address

One-to-Many

An array of entities:

// Household has many Persons
members: array of Person

// Accessing in rules:
count of household.members
for each member in household.members do ...

Special Entities

Context Entity

The "context" entity is always on the entity stack. It provides global access to shared data and configuration.

Mapping Entities

Mapping entities define how external data (XML, JSON) maps to your rule entities. This enables automatic data loading.

Using Entities in Rules

Attribute Access

// Simple attribute
person.age

// Nested access
application.household.head.name

// Array access
household.members[0].name

Creating Entities

// Create new entity
new Person

// Create and assign
set applicant = new Person
set applicant.name = "John"

Working with Arrays

// Add to array
add person to household.members

// Remove from array
remove person from household.members

// Count
count of household.members

// Iterate
for each member in household.members do
    set member.processed = true
done

// Filter
any member in household.members satisfies (member.age >= 18)

Best Practices

1. Use Meaningful Names

Entity and attribute names should be descriptive and follow consistent conventions (camelCase or snake_case).

2. Set Appropriate Defaults

Default values ensure entities are always in a valid state. Use them for flags (default false), counters (default 0), etc.

3. Document with Comments

Use the Comment column to explain the purpose of entities and attributes, especially for business-specific terms.

4. Design for Rules

Structure your entities to make rule writing easy. If rules frequently check a calculation, consider making it an attribute.

5. Separate Input and Output

Mark input attributes clearly. Output/calculated attributes should be separate to make data flow clear.

Next Steps