Ontology overview — bRRAIn Docs

What an ontology is in bRRAIn, its role, components, built-in vs custom, and versioning.

Ontology overview

An ontology is a structured vocabulary for describing things and their relationships. In bRRAIn, the ontology is the graph schema — it defines what kinds of entities exist and how they can connect.

The role of ontology in bRRAIn

Every operation — storing a record, sharing a document, resolving a conflict — results in graph nodes and edges. The ontology defines:

  1. Entity types — what can exist as a node (Person, Organization, Decision, Risk…)
  2. Relationship types — what edges can connect those nodes (authored, participated_in, mitigates…)
  3. Property schemas — what data each entity and edge can carry

Without an ontology, the graph is an unstructured blob. With it, the graph becomes queryable, auditable, and portable across systems.

Components

| Component | What it is | | --- | --- | | Entity types | Classes of things (Person, Document, Decision) | | Relationship types | Typed edges with source/target entity constraints | | Property schemas | Allowed fields on each entity and relationship | | Governance | Rules about who can modify the ontology | | Version | Every ontology change produces a new immutable version |

Built-in ontology vs custom ontology

Built-in: POPE

Every bRRAIn instance ships with the POPE model — a small, universal ontology covering:

  • People (users, employees, customers)
  • Organizations (institutions, teams, vendors)
  • Places (projects, workspaces, physical locations)
  • Events (sessions, meetings, milestones)

Plus:

  • Provenance layer — Decisions, Learnings
  • Reliability layer — Risks
  • Temporal layer — Sessions

POPE cannot be removed or renamed — it's the stable skeleton the platform relies on.

Custom: your domain model

On top of POPE, you (or the Handler, autonomously) can add domain-specific entities and relationships:

  • Legal: Case, Contract, Precedent, Clause
  • Healthcare: PatientEncounter, Diagnosis, Medication, Allergy
  • Finance: Transaction, Account, Portfolio, Tranche
  • Manufacturing: Part, Assembly, Supplier, Lot

See Extending the ontology for the full workflow.

Ontology versioning

Every change — whether operator-driven or Handler-proposed — creates a new immutable ontology version.

v1.0 → v1.1 → v1.2 → v2.0 → ...
  • Additions (new entity or relationship types) increment the minor version.
  • Deprecations (removing legacy types) require a major version bump.
  • POPE entities and core relationships are never removed — they can only be deprecated and superseded by new types.

Ontology snapshots

Snapshots are taken automatically:

  • On every Handler-proposed refinement
  • On every operator change
  • Daily, regardless of activity

Snapshots are immutable and queryable. Roll back to any prior version from the Ontology Viewer.

Ontology evolution

bRRAIn's Handler continuously observes how you write and query data. When it identifies a pattern worth promoting into the schema (e.g., a new relationship type used consistently across 100+ records), it proposes a refinement.

All Handler proposals are gated by the bRRAInCare Analyst role — nothing changes production ontology without human review unless the workspace is configured for autonomous evolution (usually only in dev/staging).

Where to go next