Modeling your data
Every other capability is configured against your data model. Matching compares attributes, validation constrains them, masking redacts them, and the API exposes them. Getting the model right first saves reworking everything else.
What you define
The data model screen. Every entity type here was defined by the tenant — the platform ships none.
| Concept | What it is |
|---|---|
| Entity type | A kind of thing you master — person, organization, place, product |
| Attribute | A named piece of data on an entity type, with a data type |
| Relationship type | A kind of link between two entity types |
The platform ships no fixed schema. Your entity types and attributes are yours, per tenant.
Attributes
Each attribute declares a data type, whether it is required, and its cardinality.
Single-value versus multi-value
The distinction matters more than it first appears, because it changes how matching and survivorship behave.
| Use single-value when | Use multi-value when |
|---|---|
| There is exactly one meaningful value — a legal name, a date of birth | The entity genuinely has several — email addresses, phone numbers, addresses |
| The field is a matching primitive compared atomically | The values form a catalog distinguished by usage |
A multi-value attribute can bind a usage type — home, work, mobile — drawn from a reference-data list. Survivorship then resolves each usage type independently: one winning home address and one winning work address, rather than one address overall.
One value per usage type may be marked preferred.
Composite attributes
Some values are structured rather than scalar. An address is not a string; it is a set of named parts.
Composite attributes are stored as structured values, and matching can target individual sub-fields — comparing postal codes exactly while comparing street lines loosely. That is not expressible if the address is one joined string.
Once structure is flattened into text it cannot be recovered reliably. Model composites as composites from the start; comparing two whole composites with a scalar comparator is rejected outright, because two entirely different addresses would otherwise compare as equal.
Reference-data binding
An attribute whose values come from a controlled list binds to a lookup type. The platform then accepts only that list's codes, and every consumer — the API, the console, matching — resolves codes to labels consistently.
Bind wherever a controlled vocabulary exists. It is the difference between
US, USA, and United States being one value or three.
Relationship types
A relationship type declares which entity types it links, its cardinality, and whether it is symmetric. It also carries display names for both directions, so one link reads correctly from either end — "employs" one way, "employed by" the other.
Modeling advice
- Model what you master. An attribute for something you keep no record of; a relationship for something you do.
- Prefer several precise attributes over one general one.
given_nameandfamily_nameare matchable;full_nameis much less so. - Bind to reference data early. Retrofitting a controlled vocabulary onto free text means cleaning every existing value.
- Standardize before you match. The matcher compares canonical values, so standardization rules are part of modeling, not an afterthought.
Next
Last verified against commit 315eb047 (2026-08-03)