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 | Alternate cross-system keys, 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 |
Prefer stable business keys (order numbers, account ids) over generated ones. Generated IDs can remain stable when resolution preserves cross-system source identities; an independently generated ID alone does not prove a match.
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.
- Prove identity on the duplicate pair before trusting the whole load.