Entity resolution

Why this exists

The same machine, department, or part shows up in many documents and projects. If each mention becomes a new node, the graph cannot answer organization-wide questions. If Yggdrasil merges on labels or similarity alone, it connects the wrong things and hides the mistake.

So automatic connection is narrow on purpose: only when approved stable identifier evidence proves the mentions are the same thing. Everything else stays separate or goes to Review.

For the difference between an entity URI, an identifier space, and an ontology term, see Entity and ontology URIs.

Problem this solves

Situation	Without this rule	With this rule
Two CSVs both use machine_id = M-001 under the same approved space	Two machine nodes, or a lucky merge that cannot be trusted	One organization entity, facts stay per project
Same label Line feeder in two notes, no ID	Silent merge of different assets	Separate entities; optional review suggestion
M-001 as machine ID and as part number	One blended node	Two nodes — different identifier spaces

Yggdrasil treats an entity as organization-wide. Projects can refer to the same department, machine, supplier, or person, while their facts and evidence stay inside each project.

The automatic connection rule

Yggdrasil connects two mentions automatically only when they carry the same stable identity URI. A label, type, alias, or similarity score is not an identifier.

SGSE uses an explicit identityPath and HTTPS identifier namespace from the structured mapping. NLP uses an identifier only when its source quote contains the stable value, such as a department ID or SKU. The resolver connects it automatically only when Ontology → Identities has approved the exact entity type, source field, and namespace for that organization. It converts the namespace and exact value into an opaque organization entity URI under https://id.yggy.tech/ (or https://id.dev.yggy.tech/ on dig).

If no stable identifier is present, or its type and source field are not approved, Yggdrasil does not mint an organization entity from that claim. Unapproved identifier fields become a proposed mapping on Ontology → Identities. Label-only mentions stay separate and can show a similar existing entity as a review suggestion.

Identity catalogs can land approved entities with no relation triples. The document overview then shows identified entities, relations, and pending identity separately. A triple count of 0 is not a complete success signal.

flowchart TD
  A[Entity mention] --> B{Stable identifier evidence?}
  B -->|Yes| C{Type and source field approved?}
  C -->|Yes| D[Create deterministic organization entity URI]
  C -->|No| P[Park claim on Identities]
  D --> E{URI already exists in the organization?}
  E -->|Yes| F[Reuse organization entity]
  E -->|No| H[Create organization entity]
  B -->|No| I[Create separate entity]
  I --> J{Similar label or type?}
  J -->|Yes| K[Show review suggestion]
  J -->|No| L[No merge suggestion]
  F --> M[Attach project-scoped fact and evidence when present]
  H --> M
  I --> M

Example: one machine in two documents

Document A is a CSV row with machine_id = M-001 and label Line feeder. Document B is a service note that mentions machine M-001. A platform operator has approved this mapping for the organization:

Field	Value
Entity type	machine (or another type that uniquely maps to this field)
Source field	machine_id
Identifier space	https://id.yggy.tech/identifier-spaces/machine/machine-id

Both extracts attach { namespaceUri, sourceField: "machine_id", value: "M-001" }. Resolve builds one organization entity URI. Both documents attach their own facts and evidence to that entity.

The value alone is not enough. Another source can use M-001 in https://id.yggy.tech/identifier-spaces/product/part-number without connecting to this machine.

If Document B contains only the label Line feeder, Yggdrasil creates a separate entity and can offer the possible match for review.

Example: kit IDs that Identities does not approve yet

Upload spare_kits.csv with kit_id = KIT-M001 and part_number = PN-440. Identities already maps product + part_number. Extraction writes the product entity. It does not mint a kit from kit_id. The document overview lists kit.kit_id with sample KIT-M001 and links to Ontology → Identities.

Approve that mapping. yggy connects the stored kit IDs without a new LLM extract. A later extract is optional.

The value KIT-M001 does not become a machine because it looks like M-001. Identifier spaces stay split.

Example: customer registry instead of a yggy space

Project A imports department_id = DE-42 in the identifier namespace https://example.com/id-spaces/departments with label Customer Operations. Project B later imports the same namespace and value with label Customer Service. A platform operator has approved https://example.com/id-spaces/departments as an identifier namespace. Both the department.department_id mapping and the namespace are approved. Both mentions resolve to one organization entity URI. Each project’s relations and source documents remain visible only in that project.

Use a customer HTTPS issuer when the organization already has one. Use a yggy /identifier-spaces/… URI only when that issuer does not exist yet (common on dig demos).

What to inspect in Review

Open Review → Entity merges to compare labels, types, identifiers, evidence, and link impact. The summary stays compact. Open Review details to see the exact identifier value and its authority namespace, then open the evidence only when you need its source context. Review also states whether the namespace could trigger automatic connection when the entity was ingested. A later allowlist change does not rewrite existing entities.

Manual merge actions remain project-authorized. A project review cannot rewrite facts from another project.