Ontology mappings

Mappings turn source rows into ontology instances. They live inside plans — usually mapping nodes — and reference the definition they build toward.

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

{
  "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": [{ "sourceKey": "billing_id", "validFrom": "first_seen" }],
  "provenance": { "system": "crm" }
}

A second example — orders with time-bounded identity:

{
  "class": "Order",
  "id": { "template": "ord-{order_no}" },
  "properties": {
    "total": { "from": "amount", "as": "number" },
    "placedAt": { "from": "created" }
  },
  "identities": [{ "sourceKey": "erp_doc", "validFrom": "created", "validTo": "delivered" }],
  "provenance": { "system": "erp" }
}

Image: entity mapping rule with class, ID template, properties, and identities filled in.

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

{
  "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" }`	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 keys	Fields proving sameness, per source system
Validity range	Optional from/to bounds for contracts, roles, addresses

Prefer stable business keys (order numbers, account ids) over generated ones — generated keys cannot match across systems by definition.

Modes

Mode	Meaning	Use for
Upsert	Create new, update known	Ongoing scheduled sync (default)
Snapshot	Incoming set replaces	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.