Entity and ontology URIs

Why this exists

Organizations upload many documents that mention the same real-world things: machines, parts, cases, people. The product only creates useful organization knowledge if those mentions resolve to one shared entity when they truly refer to the same thing — and stay separate when they do not.

Labels cannot do that job. Spelling drifts (Customer Operations vs Customer Service), types are guessed, and the same short code (M-001) can mean a machine ID in one file and a part number in another. If yggy keyed identity on labels or bare codes, it would silently merge the wrong things and split the right ones.

So yggy uses three kinds of HTTPS URI, each with one job:

Ontology terms — shared vocabulary (what kind of thing or relation).
Entity URIs — one stable node in the graph for one real-world thing.
Identifier spaces — which source ID scheme a value belongs to (evidence used to mint or reuse an entity URI).

Mixing those three is the usual confusion. An identifier space is not the machine. The machine is the entity URI minted from (organization, space, value).

Problem this solves

Failure without stable URIs	What goes wrong
Identity from labels	Same machine appears once per spelling or project
Identity from bare IDs	`M-001` as machine and `M-001` as part become one node
Invented namespaces per extract	Dig/demo runs mint `https://example.com/…` and never reuse
One public host for everything	Vocabulary, entities, and source schemes collide in meaning

The three URI jobs

Job	Host	Example	What it identifies
Vocabulary	`ontology.yggy.tech`	`https://ontology.yggy.tech/classes/organization`	A class, property, or concept
Graph entity	`id.yggy.tech`	`https://id.yggy.tech/org/org_01JACME/entities/01JENTITY`	One thing in the graph (a machine, person, case)
Identifier space	`id.yggy.tech`	`https://id.yggy.tech/identifier-spaces/machine/machine-id`	A kind of source ID, not the machine itself

yggy-hosted /identifier-spaces/… paths are not a temporary dig hack. They name a scheme when the customer has no HTTPS issuer of their own yet. Prefer a real customer registry URI when one exists.

Global and organization namespaces

Scope	Ontology URI	Entity URI	Who can access it
Global	`https://ontology.yggy.tech/classes/organization`	`https://id.yggy.tech/entities/01JGLOBAL`	Anyone
Organization	`https://ontology.yggy.tech/org/org_01JACME/classes/production_line`	`https://id.yggy.tech/org/org_01JACME/entities/01JENTITY`	Organization members

An organization ontology extends the global ontology. It can add its own classes and properties, but it cannot replace the meaning of a global term. The organization ID fixes its namespace; an overlay cannot publish terms under another organization or an external domain.

Organization resources require authentication and organization membership. yggy returns the same not-found result when a resource does not exist or the caller cannot access it. This avoids revealing private organization resources.

Identifier spaces (source ID schemes)

An identifier space is an HTTPS namespace for one governed source-field scheme. Extraction attaches evidence like this:

{
  "namespaceUri": "https://id.yggy.tech/identifier-spaces/machine/machine-id",
  "sourceField": "machine_id",
  "value": "M-001"
}

Read that as: “The value M-001 is a machine_id in this approved scheme.”

yggy then hashes (organization, namespaceUri, value) into an opaque entity URI under /org/{organizationId}/entities/…. You reuse the machine across documents when that triple matches. You do not put M-001 in the entity path.

Why the path is long

yggy-hosted spaces use:

https://id.yggy.tech/identifier-spaces/{kind}/{scheme}

Example: machine/machine-id vs product/part-number. Both can hold a value that looks like M-001; the space keeps them apart. Hyphens inside one space do not: M-001 and M001 in machine/machine-id identify the same machine. The long path is intentional structure, not a temporary name.

When to use a yggy space vs a customer registry

Situation	Use
The customer already has a stable HTTPS issuer (ERP, asset registry, GS1, …)	That issuer URI, for example `https://assets.acme.example/machines`
Dig or a demo org has no customer registry for that field	A yggy-hosted space under `/identifier-spaces/…`
Golden / benchmark fixtures	Short fixture hosts such as `https://golden.example/machines`

A tenant lists every allowed namespace for the organization on Ontology → Identities and maps extraction fields to those namespaces. Extraction fills or corrects the namespace from that map; it does not invent one from a label.

Sample mapping entry:

{
  "entityType": "machine",
  "sourceField": "machine_id",
  "namespaceUri": "https://id.yggy.tech/identifier-spaces/machine/machine-id"
}

To treat another source field as the same scheme, save a second mapping onto that space. Example: AssetRegistry entity_id values for machines are the same identifiers as asset_id. On Ontology → Identities, save:

{
  "entityType": "machine",
  "sourceField": "entity_id",
  "namespaceUri": "https://id.yggy.tech/identifier-spaces/machine/machine-id"
}

If that type and field already have a mapping, the new identifier space replaces it. Re-extract the documents afterwards. Existing graph entities do not rewrite themselves.

A mixed catalog that types from a column (field:entity_kind) still maps entity_id to the generic entity space at mapping time. After extraction, each row uses the type-specific overlay (for example machine + entity_id onto the machine space).

Dig vs production hosts

Production uses https://id.yggy.tech and https://ontology.yggy.tech. Hosted non-prod (dig) uses https://id.dev.yggy.tech and https://ontology.dev.yggy.tech with the same path shapes. Only the host changes. Entities minted on dig do not merge with entities minted on production, even when the path after the host matches.

How entity identity is decided

Labels and types describe an entity; they do not prove identity. yggy reuses an entity automatically only when an approved authority provides stable identifier evidence. An unapproved identifier field becomes a proposed mapping on Ontology → Identities. It does not mint an organization entity and it is not stored as a has_identifier graph fact.

Identity catalogs (approved IDs, no relations) still write entities. The document overview shows identified entities separately from relation triples.

Closed-domain status labels such as open and resolved have no source ID. yggy still assigns one organization URI per normalized label from /identifier-spaces/state/value. Extracting status=open in two service-case files writes one state entity. You do not map that space on Ontology → Identities, and Review does not ask you to merge those mentions.

See Entity resolution for the connection rule and review flow.

A client can send a canonical yggy entity URI to refer to an existing global or same-organization entity. The write fails when the URI is unknown or belongs to another organization, so clients cannot reserve canonical IDs themselves.

{
  "subject": {
    "label": "Assembly line 7",
    "identityUri": "https://id.yggy.tech/org/org_01JACME/entities/01JLINE7"
  },
  "predicate": "located_in",
  "object": {
    "label": "Berlin plant"
  }
}

Entity URIs are organization-wide, so two projects can refer to the same entity. Facts, documents, evidence, and provenance remain project-specific.

Availability

yggy already stores and accepts these canonical URI forms. Browser-friendly HTML and machine-readable JSON-LD or Turtle responses from id.yggy.tech and ontology.yggy.tech are not available until the resolver service is deployed. The URI remains the stable identifier before dereferencing is available.