Skip to content
Embabel Worlds

reference/

Reference (catalog / config) data a realm brings into the KG — the set of entities a realm’s types describe that should exist regardless of what the user has done. Where producers/ fetch data on demand and populate mirrors an external system, reference/ seeds a fixed, realm-authored dataset: a controlled vocabulary, a lookup catalog, a set of well-known entities. Each .yml file in reference/ is a list of records seeded (idempotently) into the KG on world load.

A record is the same {type, data, relations} shape as the create_entry tool, so it rides the same identity-MERGE and user-anchor handling — no separate write path:

# reference/streaming-services.yml — the catalog of services a Movie can be watched on
- type: StreamingService            # a declared type (types/*.yml)
  data: { serviceId: netflix, serviceName: Netflix }
- type: StreamingService
  data: { serviceId: stan, serviceName: Stan }

Semantics:

  • Idempotent. A record whose type declares an identity property is upserted on that key, so re-seeding on every boot is a no-op (or an in-place update). Types with no identity would duplicate — give reference types an identity.
  • Principal-anchored reference is per principal. The compatibility type name is userAnchor; each seeded record gets its (:AssistantUser)-[:PREDICATE]->(record) edge automatically inside the host-bound world and context — the way to seed a human principal’s preference (e.g. which services that person subscribes to). A service principal has no implicit AssistantUser anchor. Global catalog data uses userAnchor: false.
  • Relations resolve like create_entry. An optional relations: [{ predicate, to: { type, ...keyProps } }] links a record to another entry that must already exist (seed it first / in another realm’s reference/), else the record is refused.
  • Merges with virtual data. A reference type can also be a virtual-join target (e.g. StreamingService seeded here AND materialized on demand by a producer): both write paths MERGE on the shared identity, so a producer-fetched node picks up the catalog’s stable fields.

This lets a realm own its reference data as data, not as a hardcoded list inside a query or a producer — the same “it’s data, put it in the graph” discipline as types and producers.