Ontology Viewer

The Ontology Viewer is the admin dashboard for browsing, searching, and governing your bRRAIn ontology. It's the primary tool for the bRRAInCare Analyst role and the only place where Handler-proposed refinements can be approved, rolled back, or subsidized.

Accessing the Viewer

The Viewer is part of the admin GUI at https://admin.<your-instance>.brrain.io/ontology.

Required role: Architect (Tier 1) or higher, or a user explicitly granted the Care Analyst role.

Browsing entity types

The left panel lists every entity type in the current ontology, grouped by layer:

POPE
  ├─ Person
  ├─ Organization
  ├─ Place
  └─ Event

Provenance
  ├─ Decision
  └─ Learning

Reliability
  └─ Risk

Temporal
  └─ Session

Custom
  ├─ Contract     (v1.2, added 2026-03-01)
  ├─ Patient      (v1.4, added 2026-02-10)
  └─ Transaction  (v1.4, added 2026-02-10)

Click any type to see its property schema, usage statistics (records of this type), and the relationships it participates in.

Viewing relationships

The relationship panel shows every edge in the graph:

Type — canonical name (e.g., authored)
Source type — allowed source entity (e.g., Person)
Target type — allowed target entity (e.g., anything)
Properties — any data carried on the edge itself
Count — how many edges of this type exist

Use the Inspect button on any relationship to see sample edges and follow them into the graph visualizer.

Searching the ontology

The global search matches entity names, relationship names, and property names. It supports fuzzy matching and wildcards:

*patient*        # any type with "patient" in the name
author*          # authored, authorship, author_of, ...
required:yes     # filter by required-property flag

Exporting the ontology schema

Export the entire ontology — or a subset — as JSON Schema or OWL:

brrain ontology export --format jsonschema --version v1.4 > ontology-v1.4.json

Exports are useful for:

Auditing what changed between versions
Feeding the schema into external systems (e.g., a compliance tool)
Versioning custom ontology definitions in your source control

Version history and rollback

Every ontology version is snapshotted automatically. The Versions tab shows a timeline:

v1.4  2026-04-12  Added `jurisdiction` to Contract (Handler-proposed, Analyst-approved)
v1.3  2026-04-01  Added `Contract` entity type (operator-added)
v1.2  2026-03-15  Added `participated_in.role` property (Handler-proposed, auto-approved)
v1.1  2026-02-10  Initial custom ontology
v1.0  2026-01-01  POPE baseline

Click any version to:

View diff — exactly what changed vs. the prior version
Roll back — revert to that version (requires Architect + Care Analyst dual approval)
Subsidize — hide a specific entity type from the graph without deleting underlying records

Handler proposals queue

When the Handler identifies a pattern worth promoting, it lands in the Proposals queue. Each proposal includes:

Motivation — why the Handler thinks this change is needed (evidence count, example records)
Proposed change — JSON patch applied to the ontology
Impact estimate — number of records affected, query latency change
Risk flags — anything the Handler is unsure about

As Care Analyst you:

Accept — applies the change and creates a new ontology version
Reject with feedback — the Handler learns from your reasoning
Defer — keeps the proposal in the queue for later review

Governance best practices

Run a weekly Analyst review. Proposals accumulate; batch them.
Document every major version bump. Add a note when accepting a change so future Analysts can understand the history.
Never roll back silently. Rollbacks are visible to everyone; include a reason.
Subsidize before deleting. Hiding a type from the graph is reversible; deleting underlying records is not.
Export before major changes. Keep a JSON snapshot outside the Viewer for belt-and-suspenders recovery.