Skip to main content

Reasoning & Validation

A knowledge graph earns its keep when it can tell you things nobody explicitly wrote down — and refuse to accept things that contradict the model. Those are the two halves of this page: inference (derive) and SHACL validation (check).

Inference Levels

Every SPARQL query can request a reasoning level. Two levels work: Callers choose the level per query (inference= on the REST endpoint, inferenceLevel on the MCP tool). GET /api/v1/rdf/status reports the default level (NONE) and which levels are available.
rdfs and owl are no longer supported. OpenMetadata 2.1 removed the reasoner that ran inside the server process. A query that asks for rdfs, owl, owl_lite, or owl_dl fails with 503 Service Unavailable. The error message lists the levels that work. custom also returns 503 when materialized inference is not enabled. Remove these levels from saved queries, scripts, and agent prompts.

How Inference Works

Inference comes only from materialized inference. Each rule runs as a SPARQL CONSTRUCT inside the triple store and writes its results to a durable named graph, one per rule. Queries read those materialized triples directly, so the server never loads the graph into memory. To use inference, set RDF_MATERIALIZED_INFERENCE_ENABLED=true and request custom. The rule graphs are part of the triple store’s default graph, so a custom query runs unchanged and sees both asserted and inferred triples.
The settings RDF_INFERENCE_ENABLED, RDF_DEFAULT_INFERENCE_LEVEL, RDF_MAX_IN_MEMORY_INFERENCE_TRIPLES, and RDF_CACHE_INFERRED_TRIPLES are deprecated. The server ignores them and logs a warning at startup if RDF_INFERENCE_ENABLED or RDF_CACHE_INFERRED_TRIPLES is set. You can remove them from your configuration.
Staleness is the trade-off. Materialized triples are only as fresh as the last rule run. A stale rule shows a dirty flag, so you can tell when an answer may be out of date.

Materialized Inference Rules

A rule is a SPARQL CONSTRUCT query with a name, priority, and enabled flag. Its output lands in https://open-metadata.org/graph/inferred/{rule}.

The Starter Pack

Four rules ship and are always present:
Materializes indirect lineage by walking prov:wasDerivedFrom transitively, so SPARQL can answer “all upstream tables of dashboard X” without users writing property paths.
If a column carries a PII.* tag and another column receives data from it via column-level lineage, propagate the tag downstream. The derived tag is marked with om:inferredTagSource pointing at the upstream column, so a propagated tag is always distinguishable from a curated one.
This is the rule that turns “we tagged the source” into “we know every downstream column that is now also sensitive” — the question most privacy reviews actually ask.
Propagates tags down the containment hierarchy: a tag on a DatabaseSchema is inherited by every Table in it, and a tag on a Table by every Column. Inferred tags carry om:inferredTagSource.
If a Table belongs to a Domain, every Column of that table inherits the membership — so om:belongsToDomain queries return both table- and column-level results without a separate lookup.
Rules run in priority order (lower first; ties broken by name), which matters: schema→table→column tag inheritance at priority 300 runs after PII propagation at 200, so inherited tags do not feed back into the propagation pass in the same run.

Managing Rules

All admin-only. Dirty tracking: when source RDF changes after a successful materialization, the rule is flagged dirty, and GET /api/v1/rdf/rules reports that flag alongside tripleCount and lastMaterializedAt. Staleness is therefore always visible rather than silent.

Running the Materializer

Materialization is done by an application, not by the query path. RDF Inference Materialization (RdfInferenceApp) appears under Settings → Applications once RDF is enabled.
  • Schedule — every 5 minutes by default. It picks up rules whose dirty flag is set and rebuilds only those.
  • Execution — each rule runs as a SPARQL CONSTRUCT inside Fuseki, writing to that rule’s named graph. No triples pass through the OpenMetadata JVM, so materialization cost does not scale with server heap.
  • Configuration — the application accepts force (boolean, default false) to re-materialize every enabled rule even when its dirty flag is clear, and ruleName (string) to run a single named rule on demand instead of the full set.
If you have just changed a rule and do not want to wait for the next run, select Run Now on the application.

Writing Your Own Rule

A CONSTRUCT whose WHERE clause is expensive is expensive every time it materializes, over the whole graph. Validate it, then run it against a non-production dataset before enabling it in production. Unbounded property paths combined with unbound subjects are the usual culprit.

Explaining an Inference

When materialized inference is on, POST /api/v1/ontology/reasoning/explanations returns an inference explanation for a derived relation — which rules contributed, how many triples each produced, and when they last ran. This matters more than it sounds. An inferred PII tag that nobody can explain is a compliance problem, not a feature.

Custom Ontology Extensions

Extend the canonical ontology with your own classes and properties without forking it. Extensions live in a reserved namespace — https://open-metadata.org/ontology-extension/ — so a custom class can never collide with a core om: term or be mistaken for one. Each extension declares custom OWL classes and properties (object or datatype) with a description explaining why they are needed. Validation rejects URIs outside the extension namespace.
Prefer modeling in the ontology (concepts and relationship types) over extending the catalog vocabulary. Extensions are for describing kinds of metadata OpenMetadata does not have — not for describing your business, which is what the ontology is for.

SHACL Validation

SHACL (Shapes Constraint Language) is the graph equivalent of a schema check. OpenMetadata ships canonical shapes at rdf/shapes/openmetadata-shapes.ttl, loaded into https://open-metadata.org/graph/shapes, covering base entity constraints (every entity has exactly one id, one name matching ^[a-zA-Z0-9_-]+$, one FQN, at most one description, a positive version) plus per-class shapes for tables, columns, and the rest. OpenMetadata uses a second set of shapes, native-ontology-shapes.ttl, to validate ontologies when you publish a release or export one. That check runs on the ontology itself and doesn’t need the triple store.

Running It

The response is a standard sh:ValidationReport in Turtle (default) or JSON-LD. An OM-SHACL-Conforms response header carries the boolean verdict, so CI can gate on it without parsing the body. Agents call the same thing through the shacl_validate MCP tool, which additionally returns conforms and violationCount in full even when the report body is truncated.

Validation Modes

RDF_SHACL_VALIDATION_MODE controls the policy:
Validation never blocks the write path. SHACL here is a diagnostic, not a gate on entity creation — a platform that refuses to ingest a table because of a shape violation is worse than one that ingests it and tells you. ENFORCE_IMPORTS is the one place strictness is opt-in, because a malformed imported ontology corrupts a model rather than one row.

OWL Profile Guardrails

RDF_STRICT_OWL_PROFILE=true (the default) makes OpenMetadata reject authored axioms outside the supported OWL 2 DL profile. The OWL 2 DL profile keeps authored ontologies decidable, while OWL Full is undecidable. That is why the guardrail is on by default.

Next

Graph Insights

Centrality, communities, and paths over the materialized graph.

Knowledge Graph API

Every endpoint, with parameters.