Ontology & Data Catalog
Olly maintains a single, formally-modelled ontology - a shared vocabulary of the business concepts the platform is built around (PriorAuth, Coverage, Party, Claim, Policy, …) together with their definitions, their relationships, and the standards they map to. The ontology is the semantic layer that connects the language used in the domain to the actual tables, APIs, and events that implement it: every concept knows which service owns it, which architectural layer it belongs to, and which physical tables store it.
The ontology is published as a live data catalog in OpenMetadata at catalog.dev.hiolly.com. OpenMetadata is the authoritative system: it holds the glossary, the standards alignments, and the ingested inventory of every database, topic, and API across the platform, with the glossary terms linked to the physical assets they govern.
Why an ontology
A platform spread across 14 services, 22 databases, and dozens of Kafka topics accumulates a lot of subtly-overloaded vocabulary. "Member", "party", "subscriber" and "beneficiary" can mean the same thing in one service and different things in another. The ontology gives every concept exactly one definition, one canonical id, and one owning service - and records the names that used to refer to it. New engineers, LLM agents, and BI/actuarial tooling all resolve domain language through the same source of truth instead of re-guessing it.
How we model it
The model is code-first: concepts reflect what the code actually contains - Postgres schemas, OpenAPI specs, and Kafka topics are scanned, and the ontology is layered on top of that observed reality rather than hand-authored from domain guesses. Each concept is captured as a glossary term in the Olly glossary with the following structure.
Glossary terms
There are 117 terms in the Olly glossary. Each carries a definition plus a set of custom properties:
| Property | Meaning |
|---|---|
olly_id | Canonical concept id, e.g. olly:PriorAuth |
layer | Architectural layer (see below) |
owner_service | The Olly service that owns the concept |
status | Lifecycle status of the concept |
lifecycle_states | State-machine states the concept moves through |
deprecated_names | Names that previously referred to this concept |
properties | The concept's own datatype/object properties (table-of-record) |
subclass_of / disjoint_with | OWL-style relationships to other classes (text, not machine-reasoned) |
Layers
Every term is tagged with exactly one Layer classification (mutually exclusive):
| Layer | Contents |
|---|---|
contracts | API- and message-contract concepts |
data | Persisted data concepts |
domain | Core business/domain concepts |
infra | Infrastructure-level concepts |
Standards alignment
Concepts are aligned to recognised external standards so Olly's vocabulary is anchored to industry meaning rather than defined in isolation. There are 50 alignment references across five standards:
| Standard | Alignments | What it covers |
|---|---|---|
| Socotra | 33 | The underlying policy administration platform's model |
| FHIR | 7 | Healthcare data interchange resources |
| FIBO | 5 | Financial Industry Business Ontology |
| schema.org | 3 | General web/structured-data vocabulary |
| SNOMED-CT | 2 | Clinical terminology |
Relations
Concepts are linked to one another (e.g. a Claim relates to the Policy it is made against) as related-terms, so the glossary forms a connected graph rather than a flat list.
What's in the catalog
Beyond the curated glossary, OpenMetadata ingests the platform's full technical inventory and links the glossary terms onto the physical assets they govern:
| Asset type | Count | Detail |
|---|---|---|
| Postgres tables | ~80 | the Olly domain tables across the 16 service databases (the catalog excludes information_schema and infra databases like Keycloak/Temporal/Mirth) |
| Kafka topics | 9 | the platform event streams |
| API services | 14 | 41 collections / 110 endpoints (from the OpenAPI specs) |
Glossary terms are tagged directly onto the tables (and API endpoints) they describe, so you can start from a concept and jump to the exact storage that backs it - or start from a table and discover which business concept it implements. Field-level documentation is attached to the physical columns themselves: each concept's per-field descriptions are written onto the matching table columns, so the documentation is searchable and visible directly on the storage, not only on the glossary term.
Using the catalog
Browse the live catalog at catalog.dev.hiolly.com:
- Search the glossary - find a concept by name; open it to see its definition, layer, owning service, lifecycle states, and standards alignments.
- Concept → storage - from a term, follow its asset links to the Postgres tables and API endpoints tagged with it.
- Storage → concept - open any ingested table or endpoint and see which glossary term governs it.
- Explore the inventory - browse all ingested databases, schemas, topics, and API collections in one place.
Sign in with an OpenMetadata account to view the full catalog.
Where it lives
- Catalog: OpenMetadata, running on the
dev-2infrastructure host, fronted atcatalog.dev.hiolly.com. - Canonical source: OpenMetadata itself. Edit concepts, descriptions, relationships, and field docs in the catalog. OpenMetadata versions every change, and a daily
export_to_git.pyjob mirrors the catalog onto a dedicatedontology-exportgit branch for version-controlled diffs and backup. - Authoring history (frozen):
services/ontology/openmetadata/holds the original one-way projection scripts (om_*.py) that built the glossary from hand-authored YAML inontology/concepts/**. That pipeline is retired (taggedontology-yaml-final) - the scripts now refuse to run, because re-projecting would overwrite manual edits made in the catalog. The connector configs that ingest the Postgres, Kafka, and API inventory still live here.