Skip to content

Ontology-Guided Extraction

Extraction is, by default, lightly guided: the LLM is seeded with a list of preferred entity classifications and asked to prefer them, and relationship values are unguided altogether (see Indexing). That keeps recall high, but it can produce a graph in which the same idea is named several ways — Company and CORPORATION, WORKS_FOR and EMPLOYED BY.

Ontology-guided extraction lets you supply an OWL/RDFS ontology to guide the vocabulary. An ontology declares the entity types you want, the relationships permitted between them, and the attributes they carry — see Writing an ontology. It then does two things:

  1. its classes and properties, with their comments, are rendered into the extraction prompt, so the LLM is told the vocabulary rather than left to invent one; and
  2. after extraction, a deterministic filter resolves each extracted name against the ontology and — depending on how much authority you give it — rewrites it to the declared spelling, or drops what does not conform.

Optionally, values of declared datatype properties are coerced to their declared XSD type and written onto entity nodes as native graph properties, which allows for direct querying and comparison such as adding a WHERE c.foundedYear < 2000 clause to a query.

The aim is consistency, not correctness: the ontology makes the graph name things one way. It does not make the extraction true. See What the ontology does, and what it does not.

Ontology authority: how much say the ontology has

Section titled “Ontology authority: how much say the ontology has”

ontology_authority is a single knob: how much say the ontology has over what ends up in the graph. Two questions decide it — what happens to a concept the ontology declares, and what happens to one it does not:

Level Concept matches something in the ontology Concept is not in the ontology
'off' left exactly as the model emitted it left exactly as the model emitted it
'align' stored under the ontology’s name kept, under the model’s own name
'strict' stored under the ontology’s name excluded

So align governs naming, and strict governs membership.

align is the level to start at, and it is the default. It is the setting whose downside is bounded: the worst case is that some names are not folded, which is where you started. strict is not “align, but tidier” — on a corpus wider than the ontology it removes a large share of the extraction, by design. That is the right behaviour when the ontology is the specification of what belongs in the graph, and the wrong one when it is a vocabulary covering part of a broader corpus. There is no way to predict how much it would remove without running it: the level changes the prompt as well as the gates, so the model emits a different population before any gate sees it.

'off' is useful in one specific combination: with an explicit dimension override, or with typed_properties alone, when you want datatype coercion without the ontology renaming anything.

'off' is not the same as configuring no ontology at all. It suppresses the vocabulary block and every dimension, but the ontology’s class names still seed {preferred_entity_classifications} in the extraction prompt — that slot is filled independently of the level, because the level decides how much the prompt says about the vocabulary, not what the vocabulary is. If you want the prompt untouched, pass no ontology.

Underneath, the level resolves to six independent dimensions, each of which you can also set on its own:

Dimension 'off' 'align' 'strict' What it does
normalize_names False True True Rewrite a resolved name to the ontology’s authored spelling
drop_type_restatements False True True Drop a fact that carries ontology language rather than a statement about the world
enforce_entity_types False False True Drop a fact whose entity classification does not resolve
enforce_relationship_types False False True Drop a fact whose predicate does not resolve
enforce_domain_range False False True Drop a fact violating a declared rdfs:domain / rdfs:range
enforce_datatypes False False True Drop a fact whose literal does not parse as its declared XSD datatype

Every dimension gates facts, and only facts. Note what that leaves alone, because “drop” in the table above is narrower than it sounds:

  • A __Statement__ is never dropped. If strict rejects every fact a statement carried, the statement still reaches the graph and the statement vector index — with facts: 0. Its text is therefore still retrievable, even though the ontology excluded the assertion it makes.
  • topic.entities is never pruned either. That list is not written to the graph, but it is normalized and annotated, so an unresolvable classification survives in it.
  • An unknown class is not a violating one. enforce_domain_range drops a fact it can show breaches a declared domain or range; it cannot show that of a class it could not resolve, so only enforce_entity_types rejects those. The case where this is most visible is a fact whose object text the extractor never matched to a named entity: it arrives with a literal complement rather than an object entity, so there is no object class at all, and neither gate can test that side of it even at strict.

If you need the statement text itself excluded, strict is not the tool — filter the corpus, or narrow what reaches extraction.

If every dimension resolves to False and typed_properties is 'off', the filter is not added to the extraction pipeline at all.

drop_type_restatements is the one row that does not follow “align names, strict excludes”: it drops, and it is on at align. What it drops is narrow enough to be worth stating precisely, because “align keeps what the ontology does not declare” is otherwise an exact promise:

  • a predicate that is ontology language — rdf:type, rdfs:subClassOf, owl:sameAs. The prefix is required, so an attribute named DOMAIN or RANGE is untouched;
  • a type-asserting predicate whose value repeats the subject’s own classification — Meridian Freight [Company] |TYPE| Company. This is a duplicate of the entity’s class, which the graph already records, so removing it loses nothing.

Both conditions are skipped for a predicate your ontology declares: if you declare a classification property, it means what you said it means. And the second condition needs the value to match — Riverside Rovers [Sports Team] |CLASSIFICATION| football club is kept, because it says something the classification does not.

This exists because vocabulary_format='turtle' (below) makes models restate class membership as a fact, and align has no other gate that would catch it. Set it to False if you want those facts in your graph.

report_violations logs what the filter did, at INFO: per-dimension counts of names rewritten and facts dropped. It is a record of the filter’s actions, and not a measure of how far your corpus diverges from your ontology. At align the four enforce_* counts are structurally zero, because those dimensions are off. At strict they are low for a different reason: the prompt has already told the model that unlisted concepts are discarded, so what reaches a gate is only the remainder that ignored the instruction.

Counts accumulate per node batch, and each line states the number of nodes it covers, so lines add up and no single line is the total for a run.

Configure logging with set_logging_config, or you will see nothing. The filter runs inside a spawn-started extraction worker, and logging.config.dictConfig state does not cross that boundary by itself — the toolkit forwards the config it applied, which means the config has to have gone through set_logging_config. If you configured logging with logging.basicConfig() instead, workers start at the interpreter default of WARNING and the INFO report is discarded, along with anything else an extraction component logs below WARNING.

Pass an ontology to ExtractionConfig. Any source Ontology.load accepts will do, including a bare path:

from graphrag_toolkit.lexical_graph import (
ExtractionConfig, IndexingConfig, LexicalGraphIndex
)
graph_index = LexicalGraphIndex(
graph_store,
vector_store,
indexing_config=IndexingConfig(
extraction=ExtractionConfig(ontology='ontologies/news.ttl')
)
)

That gives you the defaults: ontology_authority='align', typed_properties='off'. For anything beyond the defaults, pass an OntologyConfig:

from graphrag_toolkit.lexical_graph.indexing.extract.ontology import OntologyConfig
ontology = OntologyConfig(
'ontologies/news.ttl',
ontology_authority='align', # 'off' | 'align' | 'strict'
typed_properties='subject', # 'off' | 'subject' | 'complement' | 'both'
report_violations=True, # log what the filter rewrote and dropped, at INFO
)
graph_index = LexicalGraphIndex(
graph_store,
vector_store,
indexing_config=IndexingConfig(extraction=ExtractionConfig(ontology=ontology))
)

OntologyConfig has the following parameters:

Parameter Description Default Value
ontology The ontology. Accepts an Ontology, an rdflib.Graph, or a path (str or Path) to a .ttl file. required
ontology_authority How much authority the ontology has: 'off', 'align' or 'strict'. See Ontology authority. 'align'
normalize_names Override for the level. None follows ontology_authority. None
drop_type_restatements Override for the level. On at align and strict; set False to keep facts that restate an entity’s own class. None
enforce_entity_types Override for the level. None
enforce_relationship_types Override for the level. None
enforce_domain_range Override for the level. None
enforce_datatypes Override for the level. None
report_violations Log per-dimension counts of what this filter call rewrote and dropped, at INFO, per node batch. A record of the filter’s actions, not of how far the corpus diverges from the ontology — see Reading report_violations. False
typed_properties Where a coerced attribute value is written: 'off', 'subject', 'complement' or 'both'. See Typed attribute values. 'off'
vocabulary_format How the vocabulary is written into the prompt: 'prose' renders three labelled sections, 'turtle' shows the ontology’s own source. See Vocabulary format. 'prose'

An overriding dimension is honoured whatever the level says, so OntologyConfig('news.ttl', ontology_authority='off', enforce_datatypes=True) — no vocabulary block in the prompt, but still coerce declared datatypes — is expressible and is not treated as a contradiction. The six dimensions take True, False or None only; unlike ontology_authority, typed_properties and vocabulary_format, 'off' is not a value for them and raises ValueError.

The ontology’s class names seed the preferred entity classifications, so infer_entity_classifications composes with an ontology: inference adds the domain terms the ontology does not declare, which is exactly what align permits. The one combination that is refused is InferClassificationsConfig(replace_default_classifications=True) alongside an ontology, which asks for the ontology’s own vocabulary to be discarded before the model sees it; that raises ValueError rather than picking a half to honour.

vocabulary_format chooses how the vocabulary is written down for the model, which is a separate question from how much authority it has.

'prose', the default, generates three labelled sections from the ontology — one for entity types, one for relationships, one for attributes. Each section states the output channel it belongs to, the class hierarchy is shown as indentation, and XSD ranges are written in plain language (integer, true/false, date) rather than as IRIs.

'turtle' shows the ontology’s own source instead, so rdfs:subClassOf, rdfs:domain and rdfs:range are stated formally rather than paraphrased. OWL and RDFS are notations the models have read a great deal of, and an entailment that indentation only implies is written out. What it gives up is the separation the prose sections make explicit: Turtle interleaves object and datatype properties in whatever order you authored them, so nothing in the block says which output channel a term belongs to except a sentence in the header. It also makes the prompt longer, on every chunk — by how much depends entirely on your ontology.

One behaviour worth knowing if you try 'turtle': showing the model type triples makes it more likely to emit an entity’s own class back as an attribute — Meridian Freight [Company] |TYPE| Company. drop_type_restatements is on from align upwards and removes those, so the combination is usable, but it is the reason that dimension exists.

The setting applies to the extraction call that produces entities, relationships and attributes, which is the one given the full vocabulary. Proposition extraction, which runs first when it is enabled (see Indexing), is given the class names alone whichever format you choose.

A worked example, commented throughout with the reason for each choice, ships at examples/lexical-graph/ontologies/news.ttl. Start from it rather than from an empty file.

Turtle (.ttl) is the only file format read from a path. Any other RDF serialization is supported by parsing it with rdflib and passing the resulting graph.

The toolkit reads four kinds of declaration:

  • owl:Class — an entity classification. rdfs:subClassOf is respected, so a range declared as :Company admits a :SportsTeam that is declared a subclass of it.
  • owl:ObjectProperty — a relationship between two entities, with optional rdfs:domain and rdfs:range.
  • owl:DatatypeProperty — an attribute of one entity, whose rdfs:range is an XSD datatype. These are what typed values are written from.
  • skos:altLabel — an alternative phrasing that maps onto a term. Alt labels are input only: they are never stored, they are how a model’s wording finds its way to the term you want.

rdfs:comment is not decoration. It is rendered into the extraction prompt, and it is the only place you can tell the model what a term means. A term with no comment is a bare name the model has to guess at.

These are checked once, when the ontology is loaded, and raise OntologyLoadError rather than costing you an extraction run:

  • Every class named in an rdfs:subClassOf, rdfs:domain or rdfs:range must be declared as an owl:Class in the same file. owl:imports is not followed, so a reference into an imported vocabulary is a dangling reference. Inline the terms you use. (owl:Thing is the exception — it is accepted and treated as “unconstrained” wherever it appears.)
  • rdfs:subClassOf must be acyclic.
  • A property may be an owl:ObjectProperty or an owl:DatatypeProperty, not both.
  • Every owl:DatatypeProperty must declare exactly one rdfs:range, and it must be in the XSD namespace. A range outside XSD is refused; an XSD name coercion does not implement (xsd:duration, xsd:hexBinary) loads and is treated as text, with a warning the first time a value is stored under it.

Two things load cleanly but do nothing, and warn:

  • An ontology written in the RDFS/SKOS dialect — rdfs:Class and rdf:Property rather than owl:Class, owl:ObjectProperty and owl:DatatypeProperty — yields no terms. Only the OWL declarations are read.
  • Two terms whose names fold onto the same lookup key (schema:Person alongside foaf:Person, or a class whose rdfs:label is another class’s local name) collide, and one of them becomes unreachable by every name it has.

Matched concepts are stored under the ontology’s own names, spelled exactly as you authored them: a term’s rdfs:label if it has one, and its IRI local name otherwise. Label :SportsTeam as "Sports Team" and entities of that class are stored with class = 'Sports Team'; drop the label and they are stored as SportsTeam. Pick the spelling you want to read back out of the graph and put it in the label.

How the ontology is rendered into the extraction prompt is a separate matter, and an internal detail — the section layout, the ordering, and the wording may change between releases. It does not affect what is stored. What is stable is the contract above: labels if present, local names otherwise, and comments reach the model.

One exception matters if you use typed_properties: the property key written to a node comes from the IRI local name, never from the label. Labelling :revenue as "Annual Revenue" gives a fact predicate reading Annual Revenue and a node property still keyed revenue. Label each datatype property to match its local name unless you want that split deliberately; classes and object properties are unaffected, because nothing keys a graph property from them.

What the ontology does, and what it does not

Section titled “What the ontology does, and what it does not”

The work is split between the LLM and the deterministic filter, and the split is sharper than it first looks:

  • The LLM decides which concept a phrase means. That is the whole of the semantic work. If a passage says an executive “was brought on board by” a company, only the model can decide that this is employment.
  • The filter does the rest, and only the rest: folding naming conventions on terms that already resolve, coercing literals to declared datatypes, and — at strict — checking conformance.

Set expectations accordingly. The ontology raises the ceiling on consistency, not on correctness. Extraction quality still rests on the model and the prompt.

Canonicalization also has a bounded reach: it rewrites entity classifications, fact predicates and typed values, and never the topic or statement text, which is stored as the model phrased it.

Naming folds conventions; it does not map meaning

Section titled “Naming folds conventions; it does not map meaning”

normalize_names resolves an extracted name by folding it to a convention-free key — splitting camelCase, turning underscores into spaces, lowercasing, collapsing whitespace — and looking that key up, skos:altLabels included. It does not reason about meaning:

LLM emits "WORKS FOR" -> folds to "works for" -> :worksFor -> stored as worksFor ✓
LLM emits "Works_For" -> folds to "works for" -> :worksFor -> stored as worksFor ✓
LLM emits "EMPLOYED BY" -> matches skos:altLabel -> :worksFor -> stored as worksFor ✓
LLM emits "HIRED BY" -> folds to "hired by" -> no match -> left as "HIRED BY" ✗

That last line is the important one. An unresolved predicate is never mapped. Nothing downstream rescues it: normalize_names will not rename HIRED BY to worksFor, because as far as resolution is concerned those are unrelated strings. Under align the fact passes through under its own predicate; under strict it is discarded. Either way the ontology term is not applied.

This is why the prompt block is the load-bearing part of the feature, and why a spread of HIRED BY / JOINED / worksFor in your graph is a prompt-wording problem rather than something a resolver could fix. skos:altLabel is the one lever for widening the deterministic reach, and it is best spent on in-house jargon a model could not reasonably guess — not on ordinary paraphrase, which is the model’s job.

The converse limitation matters just as much: the filter cannot tell a wrong mapping from a right one. If the model decides “acquired a stake in” is worksFor, the filter resolves it, rewrites it to the canonical name, annotates it, and — if the subject and object classes happen to satisfy rdfs:domain and rdfs:range — passes it through strict enforcement as a conforming fact.

So a confident semantic error survives, and arrives looking well-typed. Do not read a strict build as a validated one; read it as a build in which everything present has the declared shape.

By default, an attribute value reaches the graph as a string, like every other extracted value. typed_properties additionally coerces the value of a declared datatype property to its declared XSD type and writes it as a native graph property, so it can be compared, sorted and range-queried.

Given:

:foundedYear a owl:DatatypeProperty ;
rdfs:label "foundedYear" ;
rdfs:domain :Company ; rdfs:range xsd:integer ;
rdfs:comment "The four-digit year the company was founded." .

and typed_properties='subject', a company entity carries an integer foundedYear:

MATCH (c:`__Entity__`)
WHERE c.class = 'Company' AND c.foundedYear < 2000
RETURN c.value, c.foundedYear

typed_properties says where the coerced value is written. It is deliberately not folded into ontology_authority, because asking for align is asking about naming and is not thereby asking for new properties on your nodes.

With no ontology configured at all, none of this reaches your graph: no filter is added to the extraction pipeline, typed_properties resolves to 'off' and cannot be set by an environment variable, and both the emitted graph queries and the extraction prompts are byte-identical to a build from before the feature existed.

Placement Where the value is written Needs include_local_entities
'off' Nowhere. No typed property is written, and the emitted graph queries are byte-identical to a build without an ontology. (The graph itself is not, unless ontology_authority is also 'off': normalize_names rewrites classifications, and create_entity_id hashes the classification into the entity id.) —
'subject' On the subject __Entity__, keyed by the property’s own local name. No
'complement' On the complement entity, as typed_value and datatype. Yes
'both' Each of the above, to its own node. Not a fallback chain. Yes

'subject' is the recommended placement, and the only one that works without include_local_entities. It is also the one that answers the question typed properties exist for — “which companies were founded before 2000” — because the value is on the entity that has it. Complement entities are created only when include_local_entities is on (it defaults to False — see the BuildConfig parameters in Indexing), and the typed write is made from inside the branch that creates the node: it will not conjure a node the setting would have suppressed. Asking for 'complement' or 'both' with include_local_entities off is refused with a ValueError when the build pipeline is configured, rather than silently writing nothing.

An ontology whose vocabulary would collide with the graph model is refused at configuration time rather than at build time: __Entity__ owns entityId, value, search_str and class, and 'both' additionally owns typed_value and datatype. A declared datatype property with one of those names raises ValueError from OntologyConfig, scoped to the placement you actually asked for — so the check runs at 'subject' and 'both', which are the placements that key a property from the ontology’s own vocabulary, and not at 'off' or 'complement', which write nothing keyed that way. entityId is on the list because it is the property every __Entity__ MERGE keys on wherever the store’s node id is property-based (Neo4j, FalkorDB).

The typed write is additive. The string value stays exactly where it was; nothing is replaced, renamed or removed, and the __Fact__ node and its __SUBJECT__ / __OBJECT__ edges are created exactly as they would have been.

At 'subject':

(:__Entity__ {entityId: '…', value: 'Halcyon Motors', class: 'Company',
search_str: 'halcyon motors', foundedYear: 1971})

At 'complement', on the entity created for the value string itself:

(:__Entity__ {entityId: '…', value: '1971', class: '__Local_Entity__',
typed_value: 1971, datatype: 'http://www.w3.org/2001/XMLSchema#integer'})

Coercion, and what happens when it refuses

Section titled “Coercion, and what happens when it refuses”

Coercion parses the literal as its declared range. It handles lexical variation on a value that has already been stated — digit grouping ('1,994' → 1994), a named month ('March 3rd 2020' → '2020-03-03').

It does not guess at readings of the text. '$1.2bn' under xsd:double is refused, and so is 'publicly listed' under xsd:boolean. Inferring those is the extractor’s job; a coercer that guessed would be inventing data under the authority of a declared type.

A refusal is lossless at align: no typed property is written, the fact and its string value are still in the graph, and you can see the literal that would not parse. The usual casualty is a currency amount — the fix is a rdfs:comment on the property telling the model to state a bare number, as news.ttl does for :revenue.

At 'strict', enforce_datatypes is on and the fact is dropped rather than kept untyped. Refusal is lossless at align; it is not at strict.

A timezone is refused, not discarded. xsd:dateTime and xsd:time values carrying an offset or a Z — '2020-03-03T23:00:00-05:00' — do not coerce. Stripping the offset would change the value while reporting success: two spellings of the same instant would store as different strings, and -05:00 and +09:00 would store as identical ones. Converting to UTC was rejected for the same reason coercion refuses '$1.2bn' — it rewrites what the text said. For xsd:date an offset is dropped, because the value there is a calendar date and the offset only says which instant within that day it was anchored to.

The consumers typed properties exist for today are:

  • BYOKG-RAG’s schema-grounded openCypher generation. ByoKGQueryEngine reads the graph’s schema and threads it into every generation prompt, and the Cypher linker’s prompt instructs the model to use only the node types, relationship types and properties in that schema — and to handle filtering, aggregation and sorting. A typed property that appears in the schema is a property the generated query can filter on.
  • The context ontology accelerator.
  • Direct Cypher from notebooks or analytics tooling, where you write the query yourself.

Entity-scoped filtering and typed-property projection inside lexical-graph’s retrievers are intended follow-ons.

On Neptune Analytics, this is the cheapest end-to-end check that the feature has a working consumer — it is the same call BYOKG-RAG makes to discover the schema:

CALL neptune.graph.pg_schema()
YIELD schema
RETURN schema

Your declared property names should appear under nodeLabelDetails["__Entity__"]["properties"]. If they do not, nothing was written — check that typed_properties is not 'off', that the predicates actually resolved to declared datatype properties, and (for 'complement') that include_local_entities is on.

The cost of a mis-mapped predicate depends entirely on who is consuming the graph, and the two cases are very different. This is a description of current behaviour, and each half of it rests on a named default:

Within lexical-graph’s own RAG loop, the source text is the guard. include_facts defaults to False, so statements are emitted without their fact strings, and ClearChunks is one of the default formatting processors, so chunk text is emptied. What reaches the answering model is the statement — proposition text, which the proposition prompt instructs to preserve the original phrasing. So by default the answering model never sees a predicate label, an entity classification, or a fact string at all. Relationship labels are a retrieval mechanism here, not an assertion the answer rests on: a wrong worksFor cannot fabricate a claim in the answer, but it does change traversal and scoring, so its cost is retrieval precision and recall. (With include_facts=True, fact strings appear beside the proposition they came from, and the model can weigh the label against its own grounding.)

For the structured consumers, there is no text guard. BYOKG-RAG generating openCypher, the context ontology accelerator, and direct Cypher all consume the structure as truth — there is no proposition alongside it to fall back on. For them a wrong predicate is a wrong answer.

include_facts=False and ClearChunks are configuration defaults rather than design intent. If facts, canonical class names or typed properties do reach the answering context in a given configuration, this guard weakens and correct labelling matters more.

The ontology’s influence is applied once, at the moment text becomes facts. The resolved terms — the class IRI, the property IRI, the canonical name and the datatype — are written into the fact metadata during extraction and never recomputed.

So changing the ontology, changing ontology_authority, or adding a skos:altLabel has no effect on already-extracted data. It requires re-extraction, not a rebuild. This is the general form of the re-index boundary below.

One consequence worth knowing before you hit it: a build with typed_properties set, run against extraction output produced without an ontology — a checkpoint, or FileBasedDocs from an earlier run — finds no annotations and writes nothing. That case is reported rather than passing silently, but the fix is to re-extract.

Enabling an ontology is a re-index boundary

Section titled “Enabling an ontology is a re-index boundary”

Turning an ontology on — or changing one in a way that changes an authored class name — does not update an existing graph in place. normalize_names can change entity.class, and include_classification_in_entity_id defaults to True, so the entity id is derived in part from the classification. A company extracted as CORPORATION before and Company after has two different entity ids and becomes two nodes, not one.

Treat it as you would a chunking change: build into a fresh tenant or a fresh graph. Building an ontology-guided extraction into a tenant that already holds an unguided one merges two vocabularies silently, which is worse than either alone.

A subject-placed typed property is written with an unconditional SET, once per fact. Entities recur across chunks, so if two chunks state a different foundedYear for the same company, the property ends up holding whichever was processed last — and build order is not deterministic. There is no reconciliation, no first-write-wins, and no conflict signal.

This is usually fine, because the two chunks usually agree. When they do not, the graph records one value and the disagreement is only visible in the underlying __Fact__ nodes, which retain both.