references/graph-schema.md
GitHubOpenHound Graph Schema
Use this reference when editing src/<pkg>/graph.py or changing extension-wide OpenGraph node and edge property behavior.
Purpose
graph.py defines the OpenHound extension's base dataclass types for nodes, node properties, and edge properties. These types are imported by model files and lookup-related code.
Naming
Use the extension prefix consistently:
<PREFIX>NodeProperties<PREFIX>Node<PREFIX>EdgeProperties
For example, GitHub might use GHNodeProperties, GHNode, and GHEdgeProperties.
Base Node Properties
The base properties class should extend NodeProperties from openhound.core.models.entries_dataclass.
Add only fields that every node in the extension should have.
from dataclasses import dataclass
from openhound.core.models.entries_dataclass import NodeProperties as BaseProperties
@dataclass
class EXNodeProperties(BaseProperties):
"""Base properties for all nodes in the extension.
Attributes:
node_id: The platform native unique identifier.
"""
node_id: str
Every field must include docstrings specifying the attributes with a description because this is used for generated documentation.
Every collector should have one root/environment node. When a collector emits multiple resource nodes, include environmentid in the base node properties and set it to the OpenGraph ID of that root/environment node.
Node Class
The node class should extend Node from openhound.core.models.entries_dataclass and set self.id in __post_init__.
from dataclasses import dataclass, field
from openhound.core.models.entries_dataclass import Node as BaseNode
@dataclass
class EXNode(BaseNode):
properties: EXNodeProperties
kinds: list[str]
id: str = field(init=False)
def __post_init__(self):
self.id = self.properties.node_id
Node ID Rules
Prefer the platform's native opaque/global node ID when available and only when the native ID is consistent and unique.
Do not use raw integer primary keys as OpenGraph node IDs. They are not stable enough across systems and can collide across extensions.
If the platform does not expose a suitable ID, derive one from stable properties with BaseNode.guid(...):
def __post_init__(self):
self.id = self.guid(self.properties.tenant_id, self.properties.slug)
Use reproducible values only. Do not include timestamps, random values, pagination offsets or mutable display names unless they are the best stable identifier the service provides.
Edge Properties
The extension edge property class should extend EdgeProperties.
from dataclasses import dataclass
from openhound.core.models.entries_dataclass import EdgeProperties
@dataclass
class EXEdgeProperties(EdgeProperties):
reason: str | None = None
Add shared fields only when they apply broadly across extension edges. Entity-specific relationship fields can stay closer to the emitting model when appropriate.
Graph Schema Rules
- Keep
graph.pygeneric to the extension, not specific to one entity. - Avoid importing model classes into
graph.py. - Avoid importing
appintograph.py. - Do not define kind strings in
graph.py; usekinds/nodes.pyandkinds/edges.py. - Do not add compatibility aliases unless there is persisted data, shipped behavior, external consumers, or an explicit requirement.
Checklist
- Prefix classes match the service prefix.
- Base node properties extend the OpenHound base properties class.
- Node class extends the OpenHound base node class.
idis assigned in__post_init__.- Node ID is stable and string-compatible.
- Base node properties include
environmentidwhen the collector emits a root/environment node. - Every graph property contains docstrings with an "Attributes" section describing each field.
- Read
references/validate-extension.mdbefore finishing.