Graph model

The easiest way to make a graph unusable is to turn every noun into the same generic node and every connection into related_to. VegaGraph keeps a small number of distinct concepts so validation and product views remain possible.

Entity type

An entity type defines a class of node: kpi, table, service, repository, api, k8s_workload, policy or a workspace type such as risk_model.

It declares display hints, identity rules and allowed or required aspects. System types are product-owned. Workspace types can be created and evolved by authorized users.

Aspect type

An aspect is reusable structured metadata validated by JSON Schema. ownership can apply to a table, service, KPI and runbook without adding ownership columns to each entity table.

Built-in families include:

• identity, description, ownership and lifecycle;
• schema, table profile, data quality and data contract;
• KPI, metric and business definitions;
• API, messaging, repository, build, deployment and runtime metadata;
• infrastructure, security, compliance, evidence, SLO and observability;
• cost, risk, incident, approval, scorecard and sync state.

Aspect writes create versions. Current reads and history reads are separate operations, which lets a product page stay fast without giving up auditability.

{
  "aspect_type": "ownership",
  "value": {
    "teams": ["growth-data"],
    "business_owner": "vp-growth",
    "technical_owner": "data-platform-oncall"
  },
  "source_system": "manual",
  "confidence": 1.0
}

Entity

An entity is a stable node with a UUID, type, name, FQN, lifecycle/status, provenance and optional context. The FQN is workspace-unique and should survive display-name changes.

service/payments-api
repository/github/acme/payments
table/vegadb/analytics/sales/fact_orders
kpi/revenue/net_retention

Aliases preserve old names and source identifiers. A connector should update the existing entity after a rename when it can prove identity, not create a new one because the display text changed.

Field reference

A field reference is a stable address inside an aspect. Table columns, API operations, message fields, configuration keys and KPI variables usually start here.

Use a field reference when the item needs lineage and classification but not its own ownership, lifecycle and rich aspect set. Promote it to an entity later when those needs appear. This keeps a table with 8,000 columns from creating 8,000 heavyweight nodes on day one.

Relationship type

A relationship type is a directed edge contract. Examples include reads_from, writes_to, computed_from, powers, runs_on, deployed_as, documents and owns.

It defines:

• a forward and inverse label;
• allowed source and target entity types or categories;
• whether either endpoint may be a field reference;
• many_to_many, one_to_many, many_to_one or one_to_one cardinality;
• whether the edge must remain acyclic;
• whether context inheritance applies;
• a JSON schema for evidence metadata.

{
  "name": "computed_from",
  "source_constraints": { "entity_types": ["kpi", "metric"] },
  "target_constraints": { "categories": ["data"] },
  "cardinality": "many_to_many",
  "acyclic": true,
  "field_endpoints_allowed": true
}

Edge

An edge is one fact under a relationship contract. It carries source, target, optional field endpoints, context, metadata, provenance, confidence and lifecycle.

net_retention_kpi  computed_from  fact_subscription_revenue
payments-api       writes_to      payment_events
fact_orders.amount derives_from   raw_orders.total
payments-prod      runs_on        eks-prod-main

Exact duplicate edge hashes are database-unique. Cardinality and cycle checks are applied transactionally by the service. For built-in structural contains paths, VegaGraph also enforces one visible parent in a context lens so breadcrumbs do not become ambiguous.