World's first open-source enterprise world model.
The ontology is a view over what documents say
The ontology is the vocabulary a base answers questions in: classes, relations, attributes and their declarations. This file says where that vocabulary comes from, how it is governed, and how it binds to what documents say. Records: [0001], [0003], [0006], [0007], [0008], [0009], [0012], [0036], [0037], [0044]. The review side of proposals is in governance, the schema side of mappings in lakehouse-and-actions, the extraction contract in extraction.
What it does today
Three layers, and "ontology" names one of them. The open graph holds what documents say: entities with their names and type words, statements whose relation is the document's phrase, qualifiers, time mentions and quotes. The ontology holds object types, link types and properties, each with a definition, examples and regression cases, plus constraints, versioned on the recorded axis. The typed graph holds facts expressed in the ontology, computed from the open graph and marked with the ontology version it was computed under [0044]. Since 2026-09-16 extraction writes the open graph and nothing else (#731, #736); the ontology enters no extraction prompt; typed facts will come only from alignment (0044 cut 2, not built). A base extracted today holds open statements and name facts and no typed facts, so signature checks, timelines and proposals have nothing to read until alignment lands.
The tables. entity_types and relation_types (kind is relation or attribute),
entity_type_parents for multiple inheritance with one primary parent for the tree view,
relation_type_domains / relation_type_ranges checked through the subclass DAG,
entity_type_disjoint, inverseOf and subPropertyOf, the functional and inverse_functional
flags, temporal (state, event, eternal) on every relation, datatype and unit on attributes,
and relation_type_qualifiers naming the attributes an edge of that relation may carry
[0001, 0031, 0037]. A class or relation imported from a vocabulary keeps its IRI (UNIQUE (kb_id, iri)) and the export writes that IRI back; key ([a-z0-9_], at most 40 characters) is the token
the API uses, unique per base [0001, 0020].
Where a vocabulary comes from. A new base is empty: no classes, no relations, and no pack unless the person ticks one in the creation dialog [0008, 0009]. Five packs ship inside the binary (schema.org, W3C Org, PROV-O, FOAF, IOF Core), multi-select, reconciled by a static alignment table of about twenty rows, additive and without undo [0008]. An OWL file (Turtle or RDF/XML) is stored verbatim in the blob store and projected into the tables by a re-runnable derivation that reports what it did not project; a dry run precedes every import; individuals are never imported as facts [0001]. The rest is typed on the ontology page or adopted from a proposal. The self-check of [0002] runs after an import: eight defect kinds (a relation both symmetric and asymmetric, a subclass cycle, an inverse that does not point back) are shown before any fact-level check, and a base without axioms reports zero.
A type on an entity is optional and a person's decision is final. entities.type_id is
nullable; NULL means undecided, and type_source (extracted, human, inferred) keeps a person's
retype, including "no type", out of every automatic path [0009, 0001]. Same-name entities may coexist
across types and untyped [0009]. Type resolution (candidates from class descriptions and from the
classes of context neighbours, interleaved and never scored together; a class inside the current
subtree applied on its own, a cross-axis class sent to a person, each pair acknowledged once) runs
from the ontology page; extraction no longer enqueues it [0001, 0016, #736].
A class's member list can name what its members lack [#1269]. The instance list
(GET /kbs/{id}/ontology/entity-types/{type_id}/entities) takes missing_predicate, a property key
or an open phrase, and missing_direction (out, the default, with the member as subject; in;
either), and keeps only the members no live fact links by that predicate: a typed row, a derived
row, a row of the inverse (or symmetric) property from the other end, an open statement whose phrase
normalizes to it, or one whose phrase is bound to the property. The answer echoes what was matched
(missing.relation_type_id, missing.phrases); membership itself is unchanged (entities.type_id).
One statement draws one edge [#755]. The typed graph is a view, so the canvas and the entity
panel show one edge per statement: the property's name when a live typed row was computed from it,
the document's phrase when none was. The document's wording is not lost with the folded edge, it
rides on the typed one (said_as, the phrases of every statement behind that row) and the interface
shows it. Both rows stay in the ledger; this is a rule about the picture, not about what is kept.
A relation phrase binds to a property per signature [0044 cut 2, #751]. A signature is a
phrase as the documents wrote it, the class of its subject and the class of its object, or "value"
when the object is a figure, a title or a status; the classes come from the kind-word bindings, and
a side whose kind word is bound to no class is its own signature. Each signature is decided once,
after the kind words, by the same shape as [#741]: candidates are the properties whose declared
domain and range admit the two ends in either direction (an undeclared end admits anything), the
model sees the signature with three of its statements and their quotes, and two votes with the
candidates in opposite orders must agree on the property and the direction (forward when the
statement's subject is the property's subject, reverse when its object is) for the signature to
bind. When the structure fits more than ten properties (a coarse class hierarchy fits most of them),
the aligner opens a shortlist: the signature's phrase and one example sentence are embedded and
the ten properties nearest by the ontology's own vectors (embed_ontology) are shown, plus any whose
label shares a word with the phrase; without an embedding model the model sees every structural
candidate. A property without a vector never enters the shortlist, so the fingerprint of the
shapes it could bind does not change and they are never re-decided: every path that adds or
relabels an element therefore refreshes the index before alignment. The ontology agent's adoption,
like the editor's create and update handlers and an OWL import, queues embed_ontology ahead of
the alignment job; adoption queues both in the element's commit [0061]. Both aligners wait while
that job is queued or running, so the order is vectors, then kind words, then phrases. The
shortlist is part of the decision's basis, so a changed list re-asks. The candidate
properties are described once per batch and each item names only its keys. A signature the votes disagree on is undecided for the alignment queue of #725; one with no
fitting property is none, its statements stay in the open graph and it counts toward the
workbench's suggestions. Bindings live in phrase_bindings. A binding to a state property also
says what a statement dated at a single moment marks (marks: start, end or none). The aligner asks
it once, with the binding: the value is written when both votes give the same one, and a binding
without one records the ask (marks_asked_at) and waits in the alignment queue, as a person's
binding without one does. A binding made before the question is asked once, and that question only
writes the value [0053 revision, #966]. Candidates are the properties whose
declared domain and range admit the endpoint classes or an ancestor of them, and a candidate
that fits only by inheritance says so to the model. A decision stores a fingerprint of what it
considered (both ancestor closures, the admitted candidates with their updated_at); it is stale
when the fingerprint of the current inputs differs, which is what timestamps could not see: a
parent edge added or removed, an edit committed while the model was answering [0053, #807, #795].
A signature with no admissible property is recorded as none (its projection retires); one with
more candidates than the limit is undecided for the queue, not silently skipped. Kind-word
bindings carry a basis as well: each candidate class the model was shown, with its updated_at
and ancestor closure, read from one snapshot before the model is called. A reply is accepted only
if that basis still matches the rows when it is written; otherwise it is discarded and the kind
word asked again [0053 revision, #795]. Cosmetic edits to a candidate class still count as a
change.
A pushed phrase that names a declared relation binds without the model [0044 revision, #1242].
A signature from a document a statements source pushed (0054) whose phrase equals the key or label
of exactly one declared relation that is not a state, with the subject's class in its declared
domain and the object's in its declared range, is bound when the document's extraction finishes,
decided_by = 'ontology'; the extraction then queues materialize. A person's decision stands over
it, and the aligner re-decides it only once the relation stops declaring it. Anything short of that
equality, and every state relation, goes to the aligner.
A shape of statement can imply a fact of another property [0044 decision 3, migration 0073].
An implication rule is keyed like a binding (a signature) or by a kind word, names the property it
concludes, and takes its object from the statement's own object or from a reading of the object's
words: the country a demonym names, the country a place lies in, the year a phrase gives. The
aligner proposes rules once per decided signature and once per kind word (a "nothing implied"
answer is recorded so it is not asked again until the basis changes); a person approves or rejects
them on the alignment queue, and the decision commits with its job. Readings are asked of the model
once per distinct phrase by the read_phrases job and cached in phrase_readings, including "no
answer"; materialisation never calls a model — it reads the cache, writes the implied facts with the
triggering statement's evidence, marks them implied (the export carries the flag), and retires
them by source like any other typed row.
An errata agent reviews the typed graph after extraction [0044 decision 7, migration 0074]. Once
materialisation has written new rows, the errata_review job takes each document with typed facts
nobody has looked at and sends them to the model with the document, the ontology's properties and,
for each fact, the structural flag it earned: domain or range (an end outside the property's
declared kinds, through the class hierarchy), name_absent (a name that does not occur in the
document), no_date (a date property holding something that is not a date). Flagged facts go
first, the rest is sampled, and a document gets a budget of two requests. The model answers a JSON
action protocol — keep, retract, revise, or add once every given fact is answered — and every
retract, revise and add must quote the document's own words; a quote that is not in the document,
a name that is not in the base or a property that does not exist is recorded as refused and never
applied (the agent creates nothing). Each verdict is a row in errata_actions, keep included, so
a fact is reviewed once. An action passes the 0027 gate before it touches the graph: a fact with a
derived fact resting on it or whose subject was named in an answer, or a write that would give a
one-value property two values, is held for a person on the errata queue of the Review page, where
the card shows the document, the proposed change, the quote and the reason it was held. A
retraction sticks: materialisation and implication skip a (statement, property) pair an applied
errata action retracted or revised, while another document's statement of the same thing still
materialises. errata_runs keeps the per-document account (facts flagged and sampled, requests,
the endpoint's token usage) for the measure 0044 names: precision gained against correct facts
removed, at what cost.
The first measured runs (bench README, 2026-09-24) showed the agent retracting mostly what the
document did say and adding mostly what it did: so a retraction or revision now needs two votes
and a flag. A fact the structure did not doubt is never retracted by the agent alone; its retraction
is held for a person with the reason unflagged. A flagged fact the agent wants to retract is asked
about a second time, alone with the document and without the first prompt's reasons; only an explicit
"not stated" retracts, anything else becomes a keep recorded as second vote: stated. Additions were
opened the other way: a name the document contains but the base lacks becomes a new entity with its
name fact (a name the document does not contain is still refused), and a document that came out of
extraction with no typed facts at all is sent once with an empty list, so the agent can add what
alignment could not bind.
Even one edit can reopen all older automatic negative bindings on that side of the
base, requiring two votes per eligible item through batched model requests; debouncing reduces
the number of runs, not the items reconsidered. A burst of ontology edits debounces into one run
rather than one run each [#757];
a person's decision is never overwritten by the agent. A person's phrase decision commits together
with its own recomputation job and the request answers 202 with the job id; the typed graph is
recomputed by that job, never by the request, and the page learns of it through the review and
graph events or GET /kbs/{id}/jobs/{job_id} [0051]. On
the 25-document batch with a hand-written ontology of 14 classes and 28 properties, and 60 of
400 kind words bound, 423 signatures cover 861 statements: 36 bind (184 statements), 110 bind to
nothing, 1 splits the votes and 276 have no admissible property because an end is unbound; a
judge reading the chunk finds 95% of the resulting typed facts stated by the document, 4% worded
wrongly and 1% not stated. Offering every property to an unbound end raised coverage to 85
signatures and dropped the judge to 87%, and on the NVDA releases, where 15 of 230 kind words
bind, to 59%: the generic "value" attribute swallowed every cash-flow row. Coverage therefore
follows the kind-word bindings and the ontology's size, not the binder. What still goes wrong is
a phrase that carries part of the value ("下降 1.4%" bound to a change property loses its sign)
and a table section read as a change ("changes in operating assets › accounts payable").
A bound statement is a typed fact [0044 cut 2, #752]. The typed graph is computed, never
written by hand: after each phrase-alignment run, every live open statement under a bound signature
becomes one layer = 'typed' row whose predicate is the bound property, whose ends follow the
binding's direction, and whose value, world-axis interval, attestation and confidence are copied
from the statement; its evidence rows and role-word qualifiers are copied too, and
from_statement_id points back at the statement. A statement with a mood qualifier is never
materialised. The computation is a set operation and idempotent: rows whose source no longer holds
(the statement invalidated, the signature no longer bound, the property or direction changed) are
invalidated, rows that are due and missing are added, rows whose binding is unchanged keep their
id, evidence and recorded time. Several statements that produce the same triple give one row: the row is written through
the typed graph's own gate (the dedup, time refinement and closing rules of insert_fact), and
typed_fact_sources lists every statement behind it, so a row is retired only when none of its
sources holds [#753]. On the 25-document batch the 36 bound signatures give 184 typed rows.
Argument order is enforced, participation is guided. A declared domain or range shapes
candidates and never discards a fact; argument order is the key's encoding convention, so a fact
whose subject violates the domain while the object fits is swapped by the signature and marked
direction_corrected [0012]. The write-time swap left with the typed extraction path; what remains
is ontology::judge_direction on adoption (a predicate that fits neither way is left off) and on
merge (moved facts are re-checked and reported as signature violations) [0012, #736]. Under
alignment a signature's direction is decided once per signature [0044].
Growth from the corpus. Predicate words that matched nothing accumulate as proposals with their
counts; adoption is decided by counting (MIN_DOCS = 2, and MIN_SIGNALS = 3 for an LLM run),
grouped by inflectional base, named by the most frequent phrasing, folded onto an existing
equivalent (_by inverses included) with subject and object swapped; the waiting facts are
rewritten as superseding rows, undoable per batch; dismissal is remembered and counting goes on; no
axiom is ever set automatically [0003, 0007]. The loop reads typed rows only, so an open phrase is
never auto-adopted, and with the typed path gone it receives no new input until alignment [#731,
#736]. Metric and Dimension are to retire: exploration inserts no class without a proposal
[0036, 0009].
Language. label is data and follows no switch; key is never translated; description follows
knowledge_bases.ontology_lang because it was the line the model read [0004]. With no ontology in
the prompt, a description is read by people and by the aligner.
Why
- Keep the original, project what has a consumer. Discarding is irreversible; a projection can be redone when a consumer appears, so "not expressible" becomes "not yet projected" [0001].
- IRI is identity, key is the token. A key derived from a label breaks on relabel and collides across vocabularies; an IRI is a name and never an address [0001].
- A declaration can be wrong (
part_ofmarked functional produced 59 false conflicts), so types guide and never gate; order is not a claim about the world, so it is enforced, measured 57% to 4% violations with reversals 39 to 0 [0001, 0012]. - A placeholder in the ontology is control flow written as vocabulary.
concept,related_to,mapped_toand thenMetric/Dimensionwere removed on the same argument; an undecided thing stays empty and readable [0009, 0010, 0011, 0036]. - Packs give direction through structure, which prose cannot; but a pack gives types, not predicates (81% of facts unbound before bootstrap), costs ten points of type accuracy to omit and buys an ontology in the corpus's own words, so none is the default [0008].
- Counting decides adoption because the model skipped
runs_on(8 documents) and adopted a one-document verb, and a deterministic ontology makes the bench comparable; the model keeps only synonym merging, and merges stay human [0007, 0003]. - Knowledge vetoes deleting ontology: a type with entities cannot be deleted, so an import has no undo, only a bulk view of empty classes (not built) [0008].
- A qualifier definition is an attribute definition with a relation as its domain; a parallel type system was refused [0037].
- The ontology is a view. Facts bound at write time were induced by the property list (an award written as a genre): 4 to 9% not stated against 0 of 333 open statements; binding after the fact per signature costs distinct phrasings, not documents, and a changed ontology recomputes only the affected signatures instead of re-extracting [0044].
- Standard vocabularies reify events as classes, so every pack object property is a state; a
person changes
temporalon the page and reads pick it up at once, and a vocabulary that annotates a property withutopia:temporal(what the export writes) is imported with that value, a re-import updating an existing relation's [0031].
Proposed and not built
- Alignment (0044 cut 2), the rest: a signature that tells a figure from words on the value side; the parity run against the withdrawn bound pass on the typed-graph bench (#880). The prototype aligner reached 14.7% and 12.1% of gold recall in two runs against 15.5% for the withdrawn bound pass, so the bar for cut 2 is parity over two clean runs [0044, #729].
- The workbench (0044 cut 5, decided in 0061): competency questions as rows of the base and the standard an element is judged by; an ontology agent reading the unbound signatures and classless kind words against them and proposing types, properties and rules with definitions, the statements they would bind and the questions they serve; approval writes the element with its structure and re-decides those signatures; every approved element carries regression cases rerun when its definition changes; duplicate properties merged as governance.
- Exploration proposes an alignment per table through
ontology_proposals, adopted as one thing;Metric/Dimensionretire (#554, #556) [0036]. - Filtering reified-shell relations (
Action,Offer) out of pack import [0012]; Chinese descriptions generated perontology_lang[0016 C3]; a bulk view of an import's empty classes [0008].
Open questions
- What becomes of
ontology_misses, predicate adoption, type resolution and the bootstrap job once alignment lands: #736 leaves them idle; #725 proposes retiring the type machinery and adoption fromproposed_predicatein favour of the ontology agent. - Competency questions for a base that has none; when the typed graph is materialised eagerly [0044].
- Mixed-pack accuracy, Chinese labels on an English pack, and what a 1,500-term start does to
adoption thresholds never retuned [0008, 0007]; narrative verbs and
_byfolding [0007].