Skip to content
FractalOps

FractalOps Lineage Ontology v1

FractalOps Lineage Ontology v1

Section titled “FractalOps Lineage Ontology v1”

FractalOps keeps access/RBAC ontology separate from lineage/catalog ontology.

The standard ontology source of truth is the W3C-aligned TTL package under backend/src/fractalops/contexts/semantics/resources/: core.owl.ttl, taxonomy.skos.ttl, provenance.ttl, fractalops-extension.ttl, and runtime-mapping.yaml. It uses RDF 1.1, OWL 2 RL, SKOS, and PROV-O while preserving the FractalOps axes authority, asset, meaning, change, and evidence.

lineage-ontology-v1.json is now the generated compatibility freeze for graph entity kinds and relationship types used by:

  • semantics graph projection
  • DataHub catalog and project RDF steward projection
  • Valkey materialization
  • Portal lineage reads

Canonical entity kinds

Section titled “Canonical entity kinds”
  • group
  • principal
  • goldenTemplateFamily
  • stackTemplate
  • project
  • repo
  • catalogEntity
  • workspace
  • package
  • image
  • runtime
  • dataset
  • changeProposal
  • workflow
  • auditEvent
  • cluster
  • node

Canonical relationship types

Section titled “Canonical relationship types”
  • memberOf
  • inheritsFrom
  • instantiates
  • ownsProject
  • ownsRepo
  • grantsAccessTo
  • catalogVisibleTo
  • scopesWorkspace
  • backedByRepo
  • catalogedAs
  • publishesPackage
  • buildsImage
  • deploysRuntime
  • runsOn
  • targets
  • impacts
  • ownedByGroup
  • mapsToGithubPermission

Auxiliary but still allowed in v1:

  • derivedFrom
  • proposesChangeTo
  • approvedBy
  • executedBy
  • boundedBy
  • deployedAs
  • ownedBy
  • attestedBy
  • rolledBackBy
  • consumesPackage
  • managedByConnector
  • materializedAs
  • managedByGroup
  • mapsToGroup

Rules

Section titled “Rules”
  • New graph emitters must use only entity kinds and relationship types listed in lineage-ontology-v1.json.
  • Non-canonical or experimental edges must not be emitted into the main graph.
  • External IDs from GitHub, Nexus, Daytona, ClickHouse, or DataHub remain attributes, not canonical node IDs.
  • Canonical IDs stay under urn:fractalops:*.
  • Project isolation is an execution and tenancy boundary, not an ontology boundary.
  • Projects may extend the global ontology with project-local classes or fields, but those extensions must map back to global concepts with rdfs:subClassOf, skos:exactMatch, skos:closeMatch, or an explicit FractalOps mapping edge.
  • LLM, agent, PostHog, and OpenTelemetry classifiers must emit the global concept id first and project-specific detail second.

Global Core and Project Extensions

Section titled “Global Core and Project Extensions”

FractalOps knowledge accumulates only when all projects share one meaning coordinate system.

The stable shape is:

Global Ontology
  -> project extension
  -> DataHub catalog and lineage report
  -> ClickHouse event/fact row
  -> Chronicle proof reference when needed

Examples:

  • project-a:CheckoutFailure rdfs:subClassOf fops:PaymentFailure
  • project-b:PaymentGatewayTimeout skos:closeMatch fops:ExternalServiceTimeout
  • PostHog event checkout_failed maps to fops:CheckoutFailure plus project-local event properties
  • OpenTelemetry span exception maps to fops:ErrorCode / fops:Symptom plus trace/span ids

Project-local terms without a global mapping are allowed only as pending vocabulary debt. They must be visible as lineage_join_gap until an RDF steward agent maps them.

Plane separation

Section titled “Plane separation”
  • Semantics is the asset lineage truth plane. Project RDF steward agents report catalog and lineage projections into DataHub and emit the same lifecycle as normalized ClickHouse events/facts; RDF incident bundles may keep urn:li:* identifiers as attributes, but must not copy DataHub entity bodies or treat them as canonical IDs.
  • ClickHouse is the raw evidence store. warehouse.fractalops_events_raw and future OTel tables remain query/reference planes, not ontology class sources.
  • PostHog is the product-behavior event source. It does not own ontology; its events must be classified into global ontology ids and stored in ClickHouse for cross-project analysis.
  • HyperDX is the incident response DX surface for customer service logs, traces, and sessions. It is exposed as a deep link, not as ontology truth.
  • Chronicle evidence is the durable proof/provenance record plane.
  • Harness Runtime and Studios are the AI improvement and intervention plane. They consume normalized incident bundles and proof refs, not raw logs.

Runtime evidence mapping

Section titled “Runtime evidence mapping”

Runtime event fields must use OpenTelemetry Semantic Convention keys where possible, for example service.name, service.version, deployment.environment.name, error.type, exception.type, server.address, url.scheme, trace_id, and span_id. FractalOps-specific proof refs must be under the explicit fops.* extension namespace.

Build-plane duration, cache, image, source-transfer, and resource events use the terms in Build Plane Observability. Their OTLP attributes use the fractalops.build.* namespace before they are projected into ClickHouse evidence tables.

PostHog and OpenTelemetry are distributed event sources, not workflow tests. They should share these warehouse columns where possible:

  • project_slug
  • source_system (posthog, otel, rdf_steward, datahub, agent)
  • global_concept_id
  • project_concept_id
  • event_name
  • trace_id
  • span_id
  • session_id
  • actor_id
  • resource_ref
  • datahub_urn
  • chronicle_ref
  • occurred_at