Skip to content
Canonical

Relationship

Relationship

Section titled “Relationship”

Definition

Section titled “Definition”

A relationship is the controlled vocabulary of predicates the extraction pipeline may assign to a Knowledge-Graph edge — the verb in a (source, relationship, target) triple that connects two entities (for example, an organisation holds a certification, or a capability complies_with a regulation). It is the Layer-6 (Knowledge Graph) predicate vocabulary, and the allowed_relations half of the owner’s allowed_types / allowed_relations register (ID-133 Decision B). The entities at each end of an edge are typed by 34-entity-type.md.

The vocabulary is closed at v1: the 10 baseline predicates below are the complete set, and the extraction gate HARD-rejects any relationship outside it. Enforcement is the Pydantic relationship Literal on RelationshipExtraction (scripts/cocoindex_pipeline/extraction.py:423–434) — a value not in the Literal raises a ValidationError (mapped to invalid_enum), exactly mirroring the closed-enum content_type and entity_type HARD-rejects. ID-133 does not edit that gate; it documents it. The register values are sourced verbatim from that Literal so the markdown register equals the runtime Literal at authoring time.

Synonyms / Acronyms

Section titled “Synonyms / Acronyms”
  • allowed_relations — the owner’s name for this register; relationship IS the allowed_relations vocabulary (ID-133 Decision B, the allowed_types / allowed_relations pair).
  • predicate / edge type — a relationship value is the predicate (verb) of a Knowledge-Graph triple; an edge between two typed entities.

Baseline values

Section titled “Baseline values”

The 10 closed predicates, in Literal order. Each value is core and immutable at v1; the CV-level client_extensible: true is the forward bridge (see Notes), not a v1 capability.

keylabelprovenanceprovenance_modelclient_extensibleeditable_via
holdsHoldscorecorefalsedatabase_migration
complies_withComplies Withcorecorefalsedatabase_migration
delivers_toDelivers Tocorecorefalsedatabase_migration
usesUsescorecorefalsedatabase_migration
demonstrated_byDemonstrated Bycorecorefalsedatabase_migration
requiresRequirescorecorefalsedatabase_migration
part_ofPart Ofcorecorefalsedatabase_migration
supersedesSupersedescorecorefalsedatabase_migration
referencesReferencescorecorefalsedatabase_migration
evidencesEvidencescorecorefalsedatabase_migration

Relationships

Section titled “Relationships”
  • KG write-site — entity_relationships (DB table). Each relationship row stores a (source, relationship, target) triple; the relationship predicate is drawn from this vocabulary and the value stays in the Canonical DB (it is never lifted out into a markdown record).
  • Sibling — 34-entity-type.md (entity_type, Layer 5). Entity mentions are the nodes; relationship predicates are the edges between them — related_layers: [5] records the pairing. Both endpoints of an edge are typed by entity_type.
  • Provenance chain. Every relationship triple is stamped back to the source it was extracted from. Post-ID-131 the stamp’s parent FK is source_document_id (see Notes).

Consumers

Section titled “Consumers”
  • Cocoindex extraction pipeline — sole writer. extract_relationships (scripts/cocoindex_pipeline/extraction.py) emits RelationshipExtraction triples; the Pydantic relationship Literal (423–434) is the HARD-reject gate. The Literal mirrors the TS ExtractedRelationship union in lib/ai/classify.ts:653–666.
  • Parity guard — the lockstep mechanism. TestRelationshipParity (the NEW guard added in ID-133 BI-5, scripts/tests/test_cocoindex_extraction.py) binds the triple Python Literal == TS const == register fixture for relationship (the sibling of the existing TestEntityTypeParity). The public CI-visible fixture mirror is __tests__/fixtures/ontology/ontology-cv-baselines.json (expanded with relationship per ID-133 Decision A); the docs-site “parity-guard twin” keeps that fixture in lockstep with this markdown register. Drift in any of the three fails CI.
  • Knowledge Graph read surface. entity_relationships is the typed edge surface over the graph; consumers filter and traverse on relationship.

Notes

Section titled “Notes”
  • Extraction stamp parent + entities stay in the DB (BI-8). Post-ID-131 the extraction stamp’s parent FK is source_document_id (NOT content_items_id) — see ID-131 M2 / _ExtractionStamp at scripts/cocoindex_pipeline/extraction.py:261–264 for the lockstep re-parent. ID-133 does NOT edit that code (it is ID-131’s; this register only reflects it). The relationship write-site stays in the Canonical DB: relationship triples (and the entity mentions in 34-entity-type.md) do not leave the DB into a markdown record (OKF v3 §7.1 / id-131 BI-14).
  • Closed at v1; forward bridge (Decision B). All 10 predicates are core and immutable, edited only by database_migration. The CV-level client_extensible: true is the forward-compat bridge, not a v1 capability: client-extensible predicates are research-deferred to v2, mirroring content_type’s “closed for v1” posture. If the product later makes them client-extensible, the per-value provenance_model / client_extensible / editable_via keys are exactly the columns a future DB-backed provenance table would carry — promotion goes to the taxonomy_domains-style DB register, NOT to a new markdown reader (Decision A drift-avoidance).