Ontology mappings
Reference entity and relationship mappings, value expressions, source identity rules and write modes with complete JSON examples.
Mappings turn source rows into ontology instances. They live inside plans — usually mapping nodes — and reference the definition they build toward.
The examples are individual mapping-rule fragments, not complete requests.
A standalone mapping requires a valid packageId, named inputs, and entity
and relationship arrays. In a Studio node these belong under ontologyMapping.
Referenced transform functions must be installed and executable. Mapping
produces facts; a materializer or other consumer handles persistence.
Entities
| Field | Meaning |
|---|---|
| Class | Entity type built — must match the definition exactly |
| ID | Template stamped from fields, or a transform computing it |
| Properties | One value rule per property (forms below) |
| Identities | Source records behind the entity, each optionally time-bounded |
| Provenance | Fixed labels stamped on everything built |
In Pipeline Studio, ask the assistant:
Prepare a mapping rule for the ontology mapping node. Class: Customer; Id / Template: cust-{account_id}; Properties / Name / From: account_name; Properties / Tier / From: segment; Properties / Tier / As: string; Properties / Lifetime value / Transform / Function: to_number; Properties / Lifetime value / Transform / Input: ltv_raw; Properties / Is strategic / Literal: Disabled; Identities: [{"sourceNamespace": "billing", "sourceKey": "billing_id", "sourceId": {"from": "billing_id"}, "validFrom": "first_seen"}]; Provenance / System: crm. Use the actual accessible resources and required enclosing definition. Show the proposed settings and validate them before saving or executing.This request describes the example’s intent; review the generated contract and any required permissions. It does not create missing resources or make an unsupported operation available.
This is a serialized configuration/contract fragment, not a complete UI workflow. Use it only in the enclosing operation or advanced editor described on this page.
{
"class": "Customer",
"id": { "template": "cust-{account_id}" },
"properties": {
"name": { "from": "account_name" },
"tier": { "from": "segment", "as": "string" },
"lifetimeValue": { "transform": { "function": "to_number", "input": "ltv_raw" } },
"isStrategic": { "literal": false }
},
"identities": [{ "sourceNamespace": "billing", "sourceKey": "billing_id", "sourceId": { "from": "billing_id" }, "validFrom": "first_seen" }],
"provenance": { "system": "crm" }
}A second example — orders with time-bounded identity:
In Pipeline Studio, ask the assistant:
Prepare a mapping rule for the ontology mapping node. Class: Order; Id / Template: ord-{order_no}; Properties / Total / From: amount; Properties / Total / As: number; Properties / Placed at / From: created; Identities: [{"sourceNamespace": "erp", "sourceKey": "erp_doc", "sourceId": {"from": "erp_doc"}, "validFrom": "created", "validTo": "delivered"}]; Provenance / System: erp. Use the actual accessible resources and required enclosing definition. Show the proposed settings and validate them before saving or executing.This request describes the example’s intent; review the generated contract and any required permissions. It does not create missing resources or make an unsupported operation available.
This is a serialized configuration/contract fragment, not a complete UI workflow. Use it only in the enclosing operation or advanced editor described on this page.
{
"class": "Order",
"id": { "template": "ord-{order_no}" },
"properties": {
"total": { "from": "amount", "as": "number" },
"placedAt": { "from": "created" }
},
"identities": [{ "sourceNamespace": "erp", "sourceKey": "erp_doc", "sourceId": { "from": "erp_doc" }, "validFrom": "created", "validTo": "delivered" }],
"provenance": { "system": "erp" }
}Relationships
| Field | Meaning |
|---|---|
| Predicate | Relationship type — must match the definition |
| Subject / object | ID expressions for both ends — both must resolve |
| Properties | Value rules for attributes on the link itself |
| Provenance | Fixed labels like entities carry |
In Pipeline Studio, ask the assistant:
Prepare a mapping rule for the ontology mapping node. Predicate: places; Subject / Template: cust-{account_id}; Object / Template: ord-{order_no}; Properties / Order date / From: created; Provenance / System: crm. Use the actual accessible resources and required enclosing definition. Show the proposed settings and validate them before saving or executing.This request describes the example’s intent; review the generated contract and any required permissions. It does not create missing resources or make an unsupported operation available.
This is a serialized configuration/contract fragment, not a complete UI workflow. Use it only in the enclosing operation or advanced editor described on this page.
{
"predicate": "places",
"subject": { "template": "cust-{account_id}" },
"object": { "template": "ord-{order_no}" },
"properties": { "orderDate": { "from": "created" } },
"provenance": { "system": "crm" }
}Value expressions
| Form | Shape | Use for |
|---|---|---|
| From field | { "from": "field", "as": "string|number|integer|boolean|dateTime" } | Direct carries, with optional cast |
| Template | { "template": "prefix-{a}-{b}" } | IDs and labels assembled from parts |
| Transform | { "transform": { "function": "f", "input": "…" } } | Normalization, parsing, computed values |
| Literal | { "literal": value } | Constants, flags, provenance labels |
Identity rules
| Field | Meaning |
|---|---|
| Source namespace / key / ID | Source system, key name, and expression or field path yielding the actual record ID |
| Validity range | Optional from/to bounds for contracts, roles, addresses |
The ID template is the entity's identity. Two sources describe one entity only when their mappings build the same ID. Prefer stable business keys (order numbers, account IDs, tax IDs) over generated ones. A source identity records which source record described the entity; it does not merge entities.
Modes
| Mode | Meaning | Use for |
|---|---|---|
| Upsert | Create new, update known | Ongoing scheduled sync (default) |
| Snapshot | Snapshot-mode fact set; actual replacement depends on the materializer and policy | Small dimensions rebuilt wholesale |
| Delta | Change-only flows | Large state with reliable change feeds |
Choosing well
- One rule per class per plan beats scattered partial rules.
- Check that a known pair of records from two sources builds the same ID before trusting the whole load.