Ontology Modeling

Concepts (Classes): Named categories/types in your domain. Concepts can form taxonomies (is-a hierarchies), be declared disjoint, or be equivalent.

Relationships (Properties): Named relationships between entities. Properties can have a domain (applies to X) and a range (points to Y). They may be inverse or transitive.

Axioms (Rules): Constraints and entailment rules, including property chains such as: if (A --p-→ B) and (B --q-→ C) then we infer (A --r-→ C).

Inference: The process of deriving new facts (types, labels, edges) that were not explicitly stored but follow from axioms and known facts.

Object model: Encapsulate data and behavior for application code generation and persistence.

Ontology: Encode shared meaning, constraints, and inference rules that remain stable as implementation details change.

Object model: Typically uses direct references or foreign keys; traversals are hard-coded and fragile to change.

Ontology: Uses named predicates (properties) and can infer additional relationships by rules (property chains, inverses, transitivity).

Object model: Polymorphism requires class inheritance in code; cross-cutting categories are awkward to add later.

Ontology: Entities can have multiple types/labels at once. New concepts and properties can be introduced without breaking existing data.

Object model: Queries couple to concrete classes and field paths; changes force query rewrites.

Ontology: Queries target semantic relationships; reasoners can materialize edges that queries reuse, decoupling queries from implementation details.

Tight coupling: Code and queries couple to concrete field paths (customer.primaryAddress.id), making refactors risky.

Limited expressivity: Hard to encode and reuse higher-order relationships (e.g., "partners of my supplier’s parent org").

Poor polymorphism: References point to one collection/type; accommodating multiple target types requires extra code.

Performance pitfalls: Deep traversals cause extra queries, N+1 selects, or complex $lookup joins.

Decoupling via predicates: Use named predicates (e.g., hasAddress, memberOf, supplies) that remain stable while internal object fields change.

Inference for reachability: Property chains can materialize implied links (A --p-→ B & B --q-→ C ⇒ A --r-→ C), avoiding runtime multi-hop traversals.

Polymorphism-first: A predicate can connect heterogeneous types; type inferences (domain/range) remain consistent.

Query performance: Pre-materialized edges allow single-hop, index-friendly queries (in or eq filters) instead of ad-hoc multi-collection traversals.

Resilience to change: You can add or modify rules without rewriting data structures or touching referencing fields across models.

quantum-ontology-core (package com.e2eq.ontology.core)

OntologyRegistry: Holds the TBox (terminology) of your ontology.

ClassDef: Concept names and relationships (parents, disjointWith, sameAs).

PropertyDef: Property names with optional domain, range, inverse flags, and transitivity.

PropertyChainDef: Rules that define multi-hop implications (chains → implied property).

TBox: Container for classes, properties, and property chains.

Reasoner interface and ForwardChainingReasoner: Given an entity snapshot and the registry, computes inferences:

New types/labels to assert on entities.

New edges to add (implied by property chains, inverses, or other rules).

quantum-ontology-mongo (package com.e2eq.ontology.mongo)

EdgeDao: A thin DAO around an edges collection in Mongo. Each edge contains tenantId, src, predicate p, dst, inferred flag, provenance, and timestamp.

OntologyMaterializer: Runs the Reasoner for an entity snapshot and upserts the inferred edges, so queries can be rewritten to simple in/in eq filters.

quantum-ontology-policy-bridge (package com.e2eq.ontology.policy)

ListQueryRewriter: Takes a base query and rewrites it using the EdgeDao to filter by the set of source entity ids that have a specific predicate to a given destination.

This integrates ontology edges with RuleContext or policy decisions: policy asks for entities related by a predicate; the rewriter converts that into an efficient Mongo query.

quantum-ontology-policy-bridge (package com.e2eq.ontology.policy.rest)

OntologyAwareResource: Abstract REST base class that extends BaseResource to add ontology list (GET /{path}/ontology) and detail context (GET /{path}/id/{id}/ontology) endpoints. Supports ontology constraints and optional aggregation/expand for combined attributes spanning collections. See OntologyAwareResource in REST CRUD for usage.

Name relationships explicitly

Define clear predicate names (hasAddress, memberOf, supplies, owns, assignedTo). Avoid encoding relationship semantics in field names only.

Keep object model minimal and flexible

Store lightweight identifiers (ids) as needed, but avoid deeply nested reference graphs that encode traversals in code.

Model polymorphic relationships

Prefer predicates that naturally connect multiple possible types (e.g., assignedTo can target User, Team, Bot) and rely on ontology type assertions to constrain where needed.

Use property chains for common paths

If business logic often traverses A → B → C, define a chain p∘q ⇒ r and materialize r for faster queries and simpler policies.

Capture inverses and transitivity

For natural inverses (parentOf ⇄ childOf) or transitive relations (partOf, locatedIn), define them in the ontology so edges and queries stay consistent.

Keep provenance

Record why an edge exists (prov.rule, prov.inputs) so you can recompute, audit, or retract when inputs change.

Direct reference example (fragile/slow)

Query: "Find Orders whose buyer belongs to Org X or its parents."

With @Reference: requires joining Order → User → Org and recursing org.parent; costly and tightly coupled to fields.

Ontology edge example (resilient/fast)

Define predicates: placedBy(order, user), memberOf(user, org), ancestorOf(org, org). Define chain placedBy ∘ memberOf ⇒ placedInOrg.

Materialize edges: (order --placedInOrg-→ org). Also make ancestorOf transitive.

Query becomes: where order._id in EdgeDao.srcIdsByDst(tenantId, "placedInOrg", orgX).

With transitivity, you can precompute ancestor closure or add a chain placedInOrg ∘ ancestorOf ⇒ placedInOrg to include parents automatically.

Start by introducing predicates alongside existing references; do not remove references immediately.

Materialize edges for hot read paths; keep provenance so you can reconstruct.

Gradually update queries (list screens, policy filters) to use ListQueryRewriter with EdgeDao instead of deep traversals or $lookup.

Once stable, you can simplify models by removing rigid reference fields where unnecessary and rely on edges for read-side composition.

Indexing: Create compound indexes on edges: (tenantId, p, dst) and (tenantId, src, p) to support both reverse and forward lookups.

Write amplification vs read wins: Materialization adds write work, but dramatically improves read latency and simplifies queries.

Consistency: Re-materialize edges on relevant entity changes (source, destination, or intermediate) using OntologyMaterializer.

Multi-tenancy: Keep tenantId in the edge key and filters; the provided EdgeDao methods include tenant scoping.

Functional domains often map to concept clusters in the ontology. Use @FunctionalMapping to aid discovery and apply policies per area/domain.

Policies can refer to relationships semantically ("hasEdge placedInOrg OrgX") and rely on the policy bridge to turn this into efficient data filters.

Ontology-powered relationships provide a stable, semantic layer over your object model.

The Quantum Ontology modules let you define, infer, and query these relationships efficiently on MongoDB.

Compared with direct @Reference/EntityReference, ontology edges are more expressive, resilient to change, and typically faster for complex list/policy queries once materialized.

Write path (materialization):

Your domain code persists entities with minimal direct references.

An OntologyMaterializer runs when entities change to derive and upsert edges into the edges collection (per tenant).

Policy path (authorization and list filters):

The permission rule language evaluates the caller’s SecurityContext/RuleContext and produces logical filters.

When a rule asks for a semantic relationship (hasEdge), we use ListQueryRewriter + EdgeDao to translate that into efficient Mongo filters over ids.

Read path (queries):

Morphia repos apply the base data-domain filters and the rewritten ontology constraint to queries, producing fast lists without deep joins.

Signature: hasEdge(predicate, dstIdOrVar)

predicate: String name of the ontology predicate (e.g., "placedInOrg", "orderShipsToRegion").

dstIdOrVar: Either a concrete id/refName or a variable resolved from RuleContext (e.g., principal.orgRefName, request.region).

Semantics: The rule grants/filters entities for which an edge (tenantId, src = entity._id, p = predicate, dst = resolvedDst) exists.

Composition: hasEdge can be combined with existing rule clauses (and/or/not) and other filters (states, tags, ownerId, etc.).

Allow viewing Orders in the caller’s org (including ancestors via ontology closure):

allow VIEW Order when hasEdge("placedInOrg", principal.orgRefName)

Restrict list to Orders shipping to a region chosen in request:

allow LIST Order when hasEdge("orderShipsToRegion", request.region)

Always resolve tenantId from RuleContext/SecurityContext (the same source your repos use for realm/database selection).

EdgeDao and ListQueryRewriter already accept tenantId; never cross tenant boundaries when reading edges.

Index recommendation (per tenant):

(tenantId, p, dst)

(tenantId, src, p)

If your repo method builds a Bson filter before calling find(), wrap it through rewriter:

When the repo uses Morphia’s typed query API instead of BSON, pre-compute the id set and constrain by _id:

Provide one helper in your application layer, invoked wherever policies inject additional constraints:

Automatic on write via repository hook:

When you save or update an entity, the framework runs an internal PostPersistHook (OntologyWriteHook) that:

extracts explicit edges from fields/getters annotated with @OntologyProperty using a startup-built metadata cache (no per-call reflection), and

calls OntologyMaterializer to infer inverse, transitive, symmetric, and super-property edges and upsert them to the edges collection.

This is enabled by default. To disable temporarily (e.g., for bulk loads), set: ontology.auto-materialize=false

Edge rows include tenantId and should be validated/filtered by tenant on every operation.

Never trust a client-supplied predicate or destination id blindly; combine with rule evaluation and whitelist allowed predicates per domain if needed.

For shared resources across tenants (rare), model cross-tenant permissions at the policy layer; don’t reuse edges across tenants unless explicitly designed.

When writing a rule: use hasEdge("<predicate>", <rhs>) and rely on RuleContext variables for the destination when possible.

When writing a list endpoint: read optional ontology filter hints from the policy layer; if present, apply ensureHasEdge(…​) before find().

When changing domain relationships: update predicates/chains and re-materialize; list/policy code stays unchanged.

When indexing a new tenant: include the edges indexes early and validate via a smoke test query using ListQueryRewriter.

Policy: allow LIST Order when hasEdge("placedInOrg", principal.orgRefName)

Request lifecycle: 1) Security filter builds SecurityContext and RuleContext with tenantId and principal. 2) Policy evaluation returns a directive to constrain by hasEdge("placedInOrg", orgRefName). 3) Repo builds base filter (state != ARCHIVED, etc.). 4) Repo calls OntologyFilterHelper.ensureHasEdge(base, tenantId, "placedInOrg", orgRefName). 5) Mongo executes a single-hop query using materialized edges; results respect both policy and multi-tenancy.

Keep existing references for write-side integrity and local joins where simple.

Introduce ontology edges on hot read paths first; update policy rules to hasEdge and verify results.

Gradually replace deep $lookup traversals with hasEdge-based rewrites.

Ensure materialization hooks are deployed before removing data fields used as inputs to the ontology.

subClassOf (class hierarchy)

Model taxonomies (e.g., Order ⊑ Entity, Employee ⊑ Person). Used for validation and optional type filters.

subPropertyOf (property hierarchy)

If p ⊑ q and you assert (s, p, o), the system materializes (s, q, o). Queries on q will match p’s edges as well.

inverse properties

If p is the inverse of q, asserting (s, p, o) will materialize (o, q, s). Example: parentOf ⇄ childOf.

symmetric properties

For symmetric p, asserting (s, p, o) materializes (o, p, s). Example: peerOf between organizations.

transitive properties

For transitive p, if (s, p, m) and (m, p, o) then (s, p, o) is inferred. Typical for ancestorOf, partOf, locatedIn, memberOf within hierarchical contexts.

functional properties

For functional p, each source s has at most one destination o. Upserts replace the prior value. Useful for single-valued relations like placedBy on Order.

E‑commerce organizational access

Problem: “Show me all orders placed in ACME (including subsidiaries).”

Solution: Define placedBy, memberOf, placedInOrg with chain placedBy ∘ memberOf ⇒ placedInOrg, and make ancestorOf transitive. Either materialize closure with a chain placedInOrg ∘ ancestorOf ⇒ placedInOrg or use p being transitive. Queries use hasEdge("placedInOrg", orgId).

HR management

Problem: “List employees who report to VP_X directly or indirectly.”

Solution: Define reportsTo as transitive. Query hasEdge("reportsTo", "VP_X").

Third‑party and data lineage

Problem: “Which datasets are derived from Source S?”

Solution: Define derivedFrom as transitive and inverse derivedInto. Record symmetric peerOf for bidirectional partnerships where relevant.

Supplier networks (supply chain)

Problem: “Find parts supplied by a vendor’s parent company’s peers.”

Solution: Use subPropertyOf to roll up specialized edges into a common supplies predicate, define parentOf/childOf inverses, and peerOf symmetric at the org level.

Grammar/API: No changes needed. The same hasEdge/hasEdgeAny/notHasEdge functions work; results simply become more expressive as ontology features are enabled.

Feature flags: You may enable features per property (e.g., transitive) gradually. Queries remain stable.

Provenance: Keep prov so you can re‑compute or retract inferred edges when inputs or rules change.

Empty result from hasEdge: Means no matching edges exist; check whether inferences are being materialized for the predicate you expect.

Tenant scoping: All repo calls include tenantId; ensure you pass the correct tenant in both write and read paths.

Indexes: For heavy reads, ensure compound indexes on (tenantId, p, dst) and (tenantId, src, p). For functional, consider a unique (tenantId, src, p).

Testing: Use Quarkus @QuarkusTest to wire CDI and a test OntologyRegistry producer. Populate explicit edges, run the reasoner, then assert with the repo and query rewriter as shown in the integration tests included with the repository.

Single source of truth: semantics live next to the data model; less drift between code and config.

Safer refactors: renames/types evolve in code and the ontology follows.

No separate YAML/JSON needed for most use cases; optional overrides remain possible later if needed.

@OntologyClass

id: optional explicit class id (defaults to the simple class name)

subClassOf: optional extra parents (in addition to Java inheritance)

@OntologyProperty

id: optional explicit property id (defaults to the field name)

subPropertyOf: property hierarchy roll-up targets

inverseOf: name of the inverse property (declare on one side)

transitive: whether the property is transitive

symmetric: whether the property is symmetric

functional: at most one target per source (defaults to true for single-valued fields)

domain: override inferred domain (defaults to declaring @OntologyClass)

range: override inferred range (defaults to the field/element type)

ref: target ontology class id when this field represents a relationship to another ontology type

relation: the multiplicity/cardinality for the relationship (NONE, ONE_TO_ONE, ONE_TO_MANY, MANY_TO_ONE, MANY_TO_MANY)

edgeType: the edge label used in the ontology graph; if omitted, falls back to id or field name

inverseOfEdge: optional inverse edge label if you prefer naming inverses at the edge level

materializeEdge: when false, keeps the reference value but skips edge creation (defaults to true)

cascade: optional cascade policies (NONE by default). Supports ORPHAN_REMOVE, DELETE, and BLOCK_IF_REFERENCED; see below.

cascadeDepth: limit for recursive cascades (default 1); used by DELETE cascades to bound depth and prevent long chains

Direct usage (plain Java):

Quarkus auto-wiring (preferred):

What happens:

The framework inspects fields/getters annotated with @OntologyProperty and extracts explicit edges.

The reasoner applies inverse, symmetric, transitive, and subPropertyOf traits from the registry and upserts inferred edges.

When to trigger re-materialization manually:

After ontology rule changes (e.g., you mark a property transitive or add an inverse), run your re-materialization job to recompute edges for existing entities in a tenant.

During bulk imports, you can disable auto-materialize and run the job afterward.

E‑commerce org access

Annotate placedBy (functional), memberOf (transitive), and optionally parentOf (inverse childOf). Materialize placedInOrg via a property chain. Query hasEdge("placedInOrg", org).

HR reporting lines

Annotate reportsTo as transitive on Employee; query hasEdge("reportsTo", managerId).

Supplier networks

Annotate supplies as a base property; use subPropertyOf to roll up specialized suppliesDirect and suppliesViaSubsidiary to supplies; annotate peerOf on Org as symmetric.

The registry is empty at runtime

Ensure your models are discovered by Morphia (annotated with @Entity) and that the Quarkus application initializes MorphiaDatastore before the ontology producer.

Inverse not applied

Declare inverseOf on one side only; the loader will wire both directions.

Functional not enforced

For functional properties, ensure your edge repository enforces unique (tenantId, src, p) or that your write path overwrites prior values.

Start by adding @OntologyProperty to the most important relationships; don’t attempt to annotate everything at once.

Keep existing @Reference fields if you have them; use edges for query-time semantics and policy integration first.

Add tests that verify the loader discovered your properties (including inverses/subPropertyOf) and that queries via hasEdge behave as expected.

Prefer annotating getters that already exist in your schema (String ids or existing @Reference fields). Avoid adding embedded objects solely to drive ontology.

If you do need a synthetic accessor purely for ontology, hide it from API docs and persistence using @JsonIgnore, @Schema(hidden = true), and @dev.morphia.annotations.Transient.

Base path: /ontology

Media type: application/json

Security: Bearer JWT, roles user or admin

Multi‑tenancy: pass X-Realm: <tenant-id> header for ABox queries (and for any repo‑backed calls). TBox demos may work without it if your deployment wires an in‑memory registry.

GET /ontology/registry — Full TBox snapshot. Depending on your registry producer, classes may be best‑effort.

GET /ontology/classes — Lists known classes (often inferred from property domains/ranges).

GET /ontology/classes/{name} — Class details by name.

GET /ontology/properties — Lists properties.

GET /ontology/properties/{name} — Property details by name.

GET /ontology/propertyChains — Lists property chains.

GET /ontology/graph/jointjs — Returns { cells: […​] } for a quick schema visualization in JointJS.

GET /ontology/summary — Small counts summary (classes/properties/chains).

GET /ontology/graph/instances/jointjs

Headers: X-Realm: <tenant-id> (required)

Query params:

src: source id (required)

type: ontology class/type of the source id (required)

direction: out | in | both (default: out)

p: repeatable predicate filter (optional)

limit: max edges to include (default: 200)

Elements (instances) are rectangles with attrs.root data-type=instance and data-class=<Type>.

Links are labeled with the predicate. Inferred links are visually distinguished and marked in data:

Styling: dashed gray stroke (strokeDasharray: "5,5", stroke: "#9e9e9e").

Metadata: data.inferred = true.

During development: inspect whether your ontology registry is loaded as expected and whether property chains/inverses are effective.

During troubleshooting: confirm that edges exist for the predicates your queries or policies reference (see also Integrating Ontology).

For lightweight admin tools: the JointJS payload can be embedded in a simple HTML page to visualize current relationships.

Set ontology.auto-materialize=false to temporarily disable the write hook (useful for bulk loads or tests).

materializeEdge=false skips extracting explicit edges for that property only. This does not disable derived edges that might arise from other explicit inputs.

Implement OntologyEdgeProvider to contribute explicit edges not backed by fields. The extractor merges these before materialization. See Where ontology materialization happens for a full example.

For targeted repair, use the drift-repair endpoint to prune unsupported derived edges and re-derive per entity class with pagination:

Inputs: O --placedBy-→ C, C --memberOf-→ G

Implied: O --placedInOrg-→ G

Inputs: O --orderHasShipment-→ S, S --shipsTo-→ A

Implied: O --orderShipsTo-→ A

Inputs: O --orderShipsTo-→ A, A --locatedIn-→ R

Implied: O --orderShipsToRegion-→ R

Inputs: O --placedInOrg-→ G1, G1 --ancestorOf-→ G2 (ancestorOf is transitive)

Implied: O --placedInOrg-→ G2 (can repeat over the ancestor chain)