Description
Typed Relationship Vocabulary gives every connection in the Dots knowledge graph a specific, directional meaning instead of collapsing knowledge into a generic “related” link. The shipped registry covers provenance, semantic, structural, temporal, and user-authored relationships, with inverse names, allowed endpoint kinds, discovery eligibility, and graph-render color tokens. A companion entity registry binds graph node kinds such as rows, conversations, artifacts, commits, pull requests, repositories, files, and code symbols to their authoritative stores and human-ID prefixes.
The vocabulary is a developer-facing contract as well as a user-facing quality guarantee. API clients, importers, discovery jobs, traversal, and graph views can agree on what an edge means before they create or interpret it. Validation rejects unknown or structurally invalid combinations, while inverse definitions let consumers reason in either direction without inventing local terminology.
Selling Points
- Replaces ambiguous connections with verbs that communicate provenance or intent.
- Keeps importers, APIs, analytics, and visual graph consumers on one canonical vocabulary.
- Validates source and target kinds before a malformed relationship reaches storage.
- Supplies inverse relationships so directional queries remain understandable from either endpoint.
- Supports code, knowledge, conversation, and delivery entities in the same graph model.
User Story
As a developer integrating a new knowledge source, I choose an existing edge verb and declared endpoint kinds, then rely on Dots to validate and expose that relationship consistently. I do not need to invent a private schema or teach every downstream graph consumer what my connector’s links mean.
Extension Surface
The rating is extensible because the service can resolve tenant-defined overlay entries through packages/knowledge-graph/src/service.ts while preserving the governed built-in registry in packages/knowledge-graph/src/edge-types.ts. packages/knowledge-graph/src/entity-types.ts exposes the supported node-kind definitions. Extensions remain constrained by validation and cannot silently redefine a built-in verb.
Capabilities & Limits
Capabilities include category-filtered edge discovery, inverse lookup, built-in name checks, entity prefix resolution, and endpoint-pair validation. The registry also identifies system-only and automatically discoverable verbs. The honest limit is that cross-kind automatic discovery is not implied by registering types; discovery currently evaluates same-kind candidates, and a new kind pair still needs explicit inference rules and backfill design.
Implementation Map
packages/knowledge-graph/src/edge-types.tspackages/knowledge-graph/src/entity-types.tspackages/knowledge-graph/src/validate.tspackages/knowledge-graph/src/service.ts