Frequently Asked Questions¶

How do I install from npm?¶

Node.js (prebuilt native addon):

npm install ontologos

Package: npmjs.com/package/ontologos · Guide: Node.js.

WebAssembly (browser):

npm install @ontologos/wasm

Also on Wasmer: wasmer.io/eddiethedean/ontologos. Guide: WebAssembly.

Rust remains on crates.io (ontologos-* = "1.1.4"); Python on PyPI (pip install ontologos). See Install channels.

Why does `Ontology::from_file` fail?¶

Ontology::from_file on ontologos-core intentionally returns Error::ParseNotAvailable to keep the core crate free of parser dependencies.

Load OWL/RDF files with ontologos-parser:

use ontologos_parser::load_ontology;

let ontology = load_ontology(path::Path::new("ontology.owl"))?;

Or use the CLI: ontologos profile ontology.owl

See Load an OWL file.

Which crate should I depend on?¶

Pin all ontologos-* crates to the same version. Check Release status for the current crates.io version (1.1.4).

[dependencies]
ontologos-core = "1.1.4"
ontologos-parser = "1.1.4"   # OWL/RDF file loading
ontologos-profile = "1.1.4"  # EL / RL / QL / DL detection
ontologos-rl = "1.1.4"       # OWL RL saturation + RDFS (`ontologos_rl::rdfs`)
ontologos-el = "1.1.4"       # OWL EL classification
ontologos-explain = "1.1.4"  # Proof graphs
ontologos-ql = "1.1.4"        # Taxonomy queries and OWL QL
ontologos-facade = "1.1.4"   # Unified classify routing
ontologos-bridge = "1.1.4"   # Engine adapters (usually transitive)

Depend on ontologos-core only if you build ontologies programmatically or from JSON snapshots.

There is no umbrella ontologos crate on crates.io (use the listed ontologos-* crates). The npm package ontologos is the Node.js binding. The CLI binary is built from ontologos-cli in this repository.

Can I use OntoLogos instead of Protégé + HermiT today?¶

Published v1.1.4 — ontologos-dl passes the HermiT Tier A catalog (450 runnable Java + 428 OWL WG cases) and Tier B/C classification gates at a 30s per-operation budget. That is HermiT functional parity on the gated conformance corpora (parity_pct = 100% on 889 in-scope cases), not a guarantee for every real-world ontology. Composite true_parity_pct is 100% (blocking CI). See Evaluator scope for what each metric measures. For ontologies within the supported construct subset, use classify --profile dl (or profile="dl" in Python). Set ONTOLOGOS_DL_BUDGET_SECS if you need longer wall-clock limits. Outside the gated suite, validate results against HermiT/Konclude until you trust the engine on your corpus.

OntoLogos is for adopters who want to embed the Rust data model, load ontologies natively, run RL saturation, or follow the roadmap.

What is the difference between `parity_pct` and `true_parity_pct`?¶

Two metrics — do not conflate them:

Metric	Meaning	Current on `main`
`parity_pct`	In-scope HermiT catalog harness complete (zero `planned` cases)	100% (889 cases)
`true_parity_pct`	Composite everyday HermiT equivalence: minimum of literal catalog green, strict taxonomy, perf, internal ports, and SWRL rules	100%

Check live values: bash benchmarks/scripts/hermit-burndown.sh status

parity_pct = 100% is the v1.0 engineering gate — blocking in CI via check-hermit-parity-phases.sh.
true_parity_pct reached 100% on the composite burndown metric. CI runs check-true-parity-gate.sh blocking @ 100%. Details: Evaluator scope.

See Evaluator scope for the full framing.

Why was my JSON rejected?¶

Common causes:

format_version: 1 — v1 is rejected for untrusted input; use JSON v2
Invalid IRI — only http, https, and urn schemes; no control characters
Unknown entity IRI in axioms — declare all entities before referencing them in axioms
Size limits — default max JSON size is 16 MiB; see Security

Why does Pizza detect as DL?¶

Profile classification uses mapped TBox shapes (parse_meta.profile_constructs). The Pizza corpus mixes EL shapes (existentials) with constructs that rule out EL and RL (e.g. inverse and functional object properties), so detection reports DL. Diagnostics explain which mapped constructs violate EL/RL profile rules and may also list constructs seen in the source but not stored in core (e.g. ObjectAllValuesFrom).

See Profile detection.

Why doesn't `ontology.axiom_count()` match Protégé's axiom count?¶

The parser maps a subset of OWL constructs into the core model. Complex class expressions, many data-property axioms, and some property axioms are scanned for profile detection but skipped during mapping. Named ABox axioms (ClassAssertion, ObjectPropertyAssertion, SameIndividual, DifferentIndividuals) are mapped. axiom_count() is mapper output, not raw OWL logical axiom count.

See Protégé vs OntoLogos counts, Troubleshooting, and Supported constructs.

What is the difference between ROADMAP and PLAN.md?¶

docs/internal/roadmap.md is the canonical semver release plan. PLAN.md is historical background and ecosystem vision; prefer the internal roadmap for current status. The root ROADMAP.md is a short pointer.

Is OntoLogos the same as Ontologos?¶

Display name: OntoLogos. Crate and command names: ontologos-* and ontologos (lowercase).

How do I load the pizza test fixture?¶

From JSON (no download):

let json = include_str!("../tests/fixtures/pizza_minimal.json");
let ontology = Ontology::from_json(json)?;

From OWL (benchmark corpus):

./benchmarks/scripts/download.sh

let ontology = ontologos_parser::load_ontology(path::Path::new("benchmarks/data/pizza.owl"))?;

Or run cargo run -p ontologos-core --example pizza_builder.

Where is the API reference?¶

Hosted: docs.rs/ontologos-core, docs.rs/ontologos-parser, docs.rs/ontologos-profile, docs.rs/ontologos-rl, docs.rs/ontologos-el, docs.rs/ontologos-explain, docs.rs/ontologos-ql, docs.rs/ontologos-facade
Site reference: Explain API · Query API · CLI
Guides: Choosing an API · Architecture
Local: cargo doc -p ontologos-core --open
Error catalog: Error reference

Does `pip install ontologos` work?¶

Yes. The PyPI package is v1.1.4. It supports file and in-memory ontologies, incremental mutations, explain(), and optional pandas/polars export.

Profiles on PyPI: "auto", "el", "rl", "rdfs", "dl", and "swrl".

Preview only: "alc" and "dl-preview". See Install and channels.

from ontologos import Reasoner, OntologyBuilder

Reasoner(path="family.owl", profile="auto").classify()
Reasoner(path="family.owl", profile="dl").classify()

Optional extras: pip install 'ontologos[pandas]' or 'ontologos[polars]'.

See Python guide and v0.8→v0.9 migration.

When should I use `OntologyBuilder` vs loading a file?¶

Use Reasoner(path=...) when you have an OWL/RDF file on disk.

Use OntologyBuilder or Ontology.from_dict when constructing ontologies in memory (tests, pipelines, incremental edit workflows) without a parser round-trip. Pass the result to Reasoner(ontology=..., profile=...).

What does `explain()` cover?¶

Profile	Coverage
EL	Full inference traces → proof graph with IRI-resolved conclusions
RL / RDFS	Proof graph seeds asserted axioms; inferred steps lack per-rule premises until reasonable exposes a trace API
auto	Routes like `classify`; DL-detected ontologies use DL preview

See Explain API reference.

How does incremental reasoning work in Python?¶

Pass incremental=True to Reasoner, call classify(), then mutate the ontology (add_subclass_of, remove_subclass_of, add_axiom_json), and call classify() again. Each pass reuses the session when the delta is small.

See Incremental reasoning guide.

Is the Python `Reasoner` thread-safe?¶

No. Each Reasoner instance should be used from one thread at a time. Create separate instances per worker or guard access with your own synchronization.

Why does `Reasoner::classify()` on core return `NotImplemented`?¶

ontologos_core::Reasoner::classify() is a facade stub: it returns delegate hints for RDFS/RL and NotImplemented for EL. Use CLI (ontologos classify), Python (Reasoner.classify()), ontologos_facade::classify, or profile crates directly (ElClassifier, RlEngine, RdfsEngine).

Why are axioms missing after I load an OWL file?¶

Remote owl:imports are never fetched. RDF/XML (.owl, .rdf, .xml) merges local owl:imports when using load_ontology(). Turtle and OWL Functional load only the file you specify.

Workaround for remote or multi-format bundles: merge with ROBOT (robot merge --input ontology.owl --output merged.owl) or OWL API, then load the merged file. See OWL imports and Load an OWL file.

Which version should I `cargo add` or `pip install`?¶

Channel	Version	When
crates.io / PyPI (production)	1.1.4	Default for `cargo add` and `pip install ontologos`
Prior release	1.0.0	See v1.0.x → v1.1.0 migration

See Release status.

Where do I ask questions?¶

Open a GitHub issue for bugs, feature requests, or design questions. Check this FAQ and Troubleshooting first.