Entity identities and relationships

An entity ID identifies one thing. A class IRI identifies its type. A source identity identifies the record that described it. Preserve all three when mapping data so evidence and queries can connect the same order across systems.

Example names

Choose stable entity IDs, not row offsets or a newly generated ID on every run. A source key is provider-scoped; identical-looking IDs from two systems do not automatically prove that they refer to the same entity.

Map customers and their orders

You need a Semogram account, pipeline authoring access, a compiled model containing Order, Customer and placedBy, source rows with entity_id, customer_entity_id, customer_name, and a fact-store endpoint. The complete operations model defines these terms. Use a test row:

{"entity_id":"https://example.com/orders/1","customer_entity_id":"https://example.com/customers/acme","customer_name":"Acme"}

In an Ontology mapping node, add two entity rules and a relationship rule. These are mapping entries inside the node's complete configuration:

{
  "entities": [
    {
      "class": "https://example.com/operations#Order",
      "id": {
        "template": "{entity_id}"
      }
    },
    {
      "class": "https://example.com/operations#Customer",
      "id": {
        "template": "{customer_entity_id}"
      },
      "properties": {
        "https://example.com/operations#customerName": {
          "from": "customer_name",
          "as": "string"
        }
      }
    }
  ],
  "relationships": [
    {
      "predicate": "https://example.com/operations#placedBy",
      "subject": {
        "template": "{entity_id}"
      },
      "object": {
        "template": "{customer_entity_id}"
      }
    }
  ]
}

Preserve source identity entries with namespace, key and sourceId for each entity when the rows provide them. Verify the stored Order→Customer link points to the intended customer ID; a relationship label in the model graph is not an instance link.

Identity resolution and reviewed corrections

MCP identity_resolve and identity_resolve_batch accept evidence-backed observations with the incoming entityId, typeRef, source identity, names, attributes and validity. A new decision preserves the declared incoming entity ID; it does not allocate an unrelated business ID. Unresolved observations belong in the review queue.

Inspect identity_get and identity_review_queue before proposing a merge, split, reversal or resolution. Correction workflows carry evidence, rationale and expected registry revision. identity_correction_propose prepares reviewable change; do not edit a database registry directly or automatically merge merely because names match.

After an approved correction, inspect affected identity decisions, materialized references and query evidence. A correction is a separate operation from changing a class definition or rerunning a source pipeline.