Graph Index Canonical Schema

Ownership: Graph Indexer Guild • Version 2025-11-03 (Sprint 140)
Scope: Canonical node and edge schemas, attribute dictionary, identity rules, and fixture references for the Graph Indexer foundations (GRAPH-INDEX-28-001).

1. Purpose

Provide a deterministic schema contract for graph indexing pipelines.
Document the attribute dictionary consumed by SBOM, Advisory, VEX, Policy, and Runtime signal feeds.
Define the identity rules that guarantee stable node and edge identifiers across rebuilds.
Point implementers and QA to the seed fixtures used in unit/integration tests.

2. Node taxonomy

Node kind	Identity tuple (ordered)	Required attributes	Primary sources
`artifact`	`tenant`, `artifact_digest`, `sbom_digest`	`display_name`, `artifact_digest`, `sbom_digest`, `environment`, `labels[]`, `origin_registry`, `supply_chain_stage`	Scanner WebService, SBOM Service
`component`	`tenant`, `purl`, `source_type`	`purl`, `version`, `ecosystem`, `scope`, `license_spdx`, `usage`	SBOM Service analyzers
`file`	`tenant`, `artifact_digest`, `normalized_path`, `content_sha256`	`normalized_path`, `content_sha256`, `language_hint`, `size_bytes`, `scope`	SBOM layer analyzers
`license`	`tenant`, `license_spdx`, `source_digest`	`license_spdx`, `name`, `classification`, `notice_uri`	SBOM Service, Concelier
`advisory`	`tenant`, `advisory_source`, `advisory_id`, `content_hash`	`advisory_source`, `advisory_id`, `severity`, `published_at`, `content_hash`, `linkset_digest`	Concelier
`vex_statement`	`tenant`, `vex_source`, `statement_id`, `content_hash`	`status`, `statement_id`, `justification`, `issued_at`, `expires_at`, `content_hash`	Excititor
`policy_version`	`tenant`, `policy_pack_digest`, `effective_from`	`policy_pack_digest`, `policy_name`, `effective_from`, `expires_at`, `explain_hash`	Policy Engine
`runtime_context`	`tenant`, `runtime_fingerprint`, `collector`, `observed_at`	`runtime_fingerprint`, `collector`, `observed_at`, `cluster`, `namespace`, `workload_kind`, `runtime_state`	Signals, Zastava
`asset`	`tenant`, `type`, `source`, `external_id`	`schema_version`, `asset_id`, `type`, `tenant_id`, `source`, `external_id`, `criticality`, `ownership`, `depends_on`, `asset_attributes`, `first_seen`, `last_seen`, `tombstone`	Graph Asset Registry

3. Edge taxonomy

Edge kind	Source → Target	Identity tuple (ordered)	Required attributes	Default validity
`CONTAINS`	`artifact` → `component`	`tenant`, `artifact_node_id`, `component_node_id`, `sbom_digest`	`detected_by`, `layer_digest`, `scope`, `evidence_digest`	`valid_from = sbom_collected_at`, `valid_to = null`
`DEPENDS_ON`	`component` → `component`	`tenant`, `component_node_id`, `dependency_purl`, `sbom_digest`	`dependency_purl`, `dependency_version`, `relationship`, `evidence_digest`	Derived from SBOM dependency graph
`DECLARED_IN`	`component` → `file`	`tenant`, `component_node_id`, `file_node_id`, `sbom_digest`	`detected_by`, `scope`, `evidence_digest`	Mirrors SBOM declaration
`BUILT_FROM`	`artifact` → `artifact`	`tenant`, `parent_artifact_node_id`, `child_artifact_digest`	`build_type`, `builder_id`, `attestation_digest`	Derived from provenance attestations
`AFFECTED_BY`	`component` → `advisory`	`tenant`, `component_node_id`, `advisory_node_id`, `linkset_digest`	`evidence_digest`, `matched_versions`, `cvss`, `confidence`	Concelier overlays
`VEX_EXEMPTS`	`component` → `vex_statement`	`tenant`, `component_node_id`, `vex_node_id`, `statement_hash`	`status`, `justification`, `impact_statement`, `evidence_digest`	Excititor overlays
`GOVERNS_WITH`	`policy_version` → `component`	`tenant`, `policy_node_id`, `component_node_id`, `finding_explain_hash`	`verdict`, `explain_hash`, `policy_rule_id`, `evaluation_timestamp`	Policy Engine overlays
`OBSERVED_RUNTIME`	`runtime_context` → `component`	`tenant`, `runtime_node_id`, `component_node_id`, `runtime_fingerprint`	`process_name`, `entrypoint_kind`, `runtime_evidence_digest`, `confidence`	Signals/Zastava ingestion
`ASSET_VERSION`	`asset` -> `asset`	`tenant`, `asset_id`, `event_type`, `previous_asset_hash`, `current_asset_hash`	`schema_version`, `asset_id`, `event_type`, `previous_asset_hash`, `current_asset_hash`, `effective_at`, `tombstone`	Asset registry lineage

4. Attribute dictionary

Attribute	Type	Applies to	Description
`tenant`	`string`	nodes, edges	Tenant identifier (enforced on storage and query).
`kind`	`string`	nodes, edges	One of the values listed in the taxonomy tables.
`canonical_key`	`object`	nodes	Ordered tuple persisted as a JSON object matching the identity tuple components.
`id`	`string`	nodes, edges	Deterministic identifier (`gn:` or `ge:` prefix + Base32-encoded SHA-256).
`hash`	`string`	nodes, edges	SHA-256 of the canonical JSON representation (normalized by sorted keys).
`attributes`	`object`	nodes, edges	Domain-specific attributes (all dictionary keys kebab-case).
`provenance`	`object`	nodes, edges	Includes `source`, `collected_at`, `sbom_digest`, `attestation_digest`, `event_offset`.
`valid_from`	`string (ISO-8601)`	nodes, edges	Inclusive timestamp describing when the record became effective.
`valid_to`	`string (ISO-8601 or null)`	nodes, edges	Exclusive timestamp; `null` means open-ended.
`scope`	`string`	nodes, edges	Scope label (e.g., `runtime`, `build`, `dev-dependency`).
`labels`	`array[string]`	nodes	Free-form but deterministic ordering (ASCII sort).
`confidence`	`number`	edges	0-1 numeric confidence score for overlay-derived edges.
`evidence_digest`	`string`	edges	SHA-256 digest referencing the immutable evidence payload.
`linkset_digest`	`string`	nodes, edges	SHA-256 digest to Concelier linkset documents.
`explain_hash`	`string`	nodes, edges	Hash of Policy Engine explain trace payload.
`runtime_state`	`string`	`runtime_context` nodes	Aggregated runtime state (e.g., `Running`, `Terminated`).
`asset_id`	`string`	`asset` nodes, `ASSET_VERSION` edges	Deterministic Graph node id for the asset.
`type`	`string`	`asset` nodes	One of `host`, `container`, `image`, `service`, `integration`, `plugin`.
`ownership`	`object`	`asset` nodes	Opaque `ownerActorRef`, `ownerTeamRef`, and `credentialRefs`; no dereferenced secrets or PII.
`tombstone`	`boolean`	`asset` nodes, `ASSET_VERSION` edges	True when an asset has been removed but retained for lineage.

5. Identity rules

Node IDs (gn: prefix).
id = "gn:" + tenant + ":" + kind + ":" + base32(sha256(identity_tuple))
identity_tuple concatenates tuple components with | (no escaping) and lower-cases both keys and values unless the component is a hash or digest.
Edge IDs (ge: prefix).
id = "ge:" + tenant + ":" + kind + ":" + base32(sha256(identity_tuple))
Edge tuples must include the resolved node IDs rather than only the canonical keys to ensure immutability under re-key events.
Hashes.
hash is computed by serializing the canonical document with:
- UTF-8 JSON
- Object keys sorted lexicographically
- Arrays sorted where semantics allow (e.g., labels, matched_versions)
- Timestamps normalized to UTC ISO-8601 (YYYY-MM-DDTHH:MM:SSZ)
Deterministic provenance.
provenance.source is a dotted string (scanner.sbom.v1, concelier.linkset.v1) and provenance.event_offset is a monotonic integer for replay.

6. Validity window semantics

valid_from equals the upstream event timestamp at ingestion time (SBOM collected timestamp, advisory published timestamp, policy evaluation timestamp, runtime observation timestamp).
valid_to stays null until a newer version supersedes the record. Superseding records carry a supersedes reference in attributes.
Snapshots freeze the set of nodes/edges with valid_from <= snapshot_at < coalesce(valid_to, +∞).

7. Fixtures & verification

Seed fixtures live under tests/Graph/StellaOps.Graph.Indexer.Tests/Fixtures/v1/.
Fixture files:
- nodes.json — canonical node samples (per node kind).
- edges.json — canonical edge samples including overlay references.
- schema-matrix.json — lists attribute coverage per node/edge kind for regression tests.
Unit tests assert:
- Identifier determinism (GraphIdentityTests.NodeIds_are_stable).
- Hash determinism under property ordering variations.
- Attribute coverage against schema-matrix.json.
Fixtures follow the attribute dictionary above; new attributes require dictionary updates and fixture refresh.

8. Change control

Increment schema version in fixture folder (v1, v2, …) when making breaking changes.
Update this document and the JSON fixtures together; do not ship mismatched versions.
Notify SBOM Service, Concelier, Excititor, Policy, Signals, and Zastava owners before promoting changes to DOING/DONE state.

9. References

docs/modules/graph/architecture.md — high-level architecture.
docs/modules/platform/architecture-overview.md — platform context.
docs/contracts/asset-registry-v1.md — asset registry v1 contract.
docs/modules/graph/asset-registry.md — asset registry module dossier.
src/Graph/StellaOps.Graph.Indexer/TASKS.md — task tracking.
src/__Tests/__Datasets/seed-data/ — additional sample payloads for offline kit packaging (future work).