--- title: "How to Build an Organizational Ontology: A Practical Guide" slug: "how-to-build-an-organizational-ontology" author: "Mikel Amigot" date: "2026-07-16 10:30:00" category: "Premium" topics: "how to build an ontology, organizational ontology, ontology creation process, semantic layer, entity types, knowledge graph, MCP connectors, data unification, ontology governance, self-hosted AI" summary: "A practical, step-by-step guide to building an organizational ontology: model the nouns, add the verbs, connect your systems once over MCP, govern access by role, and ship the whole layer from a CLI — open source, self-hosted, and owned by you." banner: "" thumbnail: "" --- ## The Short Answer **Building an organizational ontology is a four-move process: model the nouns (entity types, attributes, relationships), model the verbs (actions, functions, permissions), connect your source systems once over MCP, and govern access by role.** You model in business terms — a bank's accounts and transactions, a hospital's patients and encounters, a university's students and courses — so domain experts can validate the map directly, without reading a schema. With ibl.ai's open-source implementation (MIT-licensed, [github.com/iblai/ontology](https://github.com/iblai/ontology)) you stand the whole layer up from a CLI inside your own network: connectors for 22 common systems, read-only enforcement, role-scoped access, and Docker Compose deployment. You own the code, the data, and the graph — nothing is extracted to anyone's cloud. Start with one domain, ship one agent on it, and let the ontology grow with usage. ## Start with the Nouns: Model the Semantic Layer The first step in creating an ontology for any domain is modeling what exists in it — the semantic layer. Three primitives do the work: entity types, attributes, and relationships. **Entity types** are schema definitions of real-world objects or events. Each type has instances: an "Account" type contains individual accounts, a "Patient" type contains individual patients, a "Course" type contains individual courses. **Attributes** capture characteristics — an attribute type defines the shape (text, number, date, location), and an attribute value is the data on a specific instance. Balance, admission date, capacity, GPA. **Relationships** are typed connections that carry meaning. They can be one-to-one, one-to-many, or many-to-many, and can link entities of the same type — a transaction *posts to* an account, a patient *has* an encounter, a student *enrolls in* a course. The rule that keeps this step honest: use the terms your teams use every day. The same primitives express any domain:
Primitive Bank Hospital University
Entity types Account, Transaction, Customer Patient, Encounter, Provider Student, Course, Department
Attributes Balance, open date, risk tier Admission date, diagnosis code Enrollment date, GPA, capacity
Relationships Transaction posts to Account Patient has Encounter Student enrolls in Course
Actions Flag transaction, close account Schedule encounter, discharge Enroll student, approve request
When the model grows, richer abstractions keep it clean. **Interfaces** are abstract shapes multiple entity types implement — a "Facility" interface shared by branches, clinics, and campuses. **Structured attributes** group related fields (street, city, postal code) into one property while preserving field-level access. Validate this layer with domain experts, not engineers. If the people who run admissions, claims, or treasury can read the map and say "yes, that's our world," the semantic layer is right. For the conceptual grounding behind these primitives, see [what a data ontology is](https://ibl.ai/blog/what-is-a-data-ontology). ## Add the Verbs: Model the Operational Layer An ontology that only describes the world is a diagram; one that governs change in it is infrastructure. The second step is the operational layer — the verbs. **Actions** are controlled operations that create, modify, or remove entities and relationships in a single transaction. Each action enforces validation rules and can trigger side effects like notifications. Enroll a student, schedule an encounter, flag a transaction. **Functions** encode logic — code that reads entity attributes, traverses relationships, and returns computed results. They power derived metrics, complex validations, and any server-side computation an agent needs at decision time: calculate GPA, assess a risk score, route an approval. **Derived attributes** are values calculated live from the graph — a department's average satisfaction score, a customer's total exposure, a device's most recent inspection — with no redundant data stored. **Permissions** govern who can do what, at every level. The key design decision: agents inherit the same permissions as the users they serve — no special access, no backdoors. Model this from the beginning, because retrofitting access control after agents ship is far harder. Treat actions as first-class citizens. Every entity type, relationship, and action should support a real decision someone needs to make; if no one will ever query it or act on it, it doesn't belong in the ontology yet. ## Connect Your Systems Once With the model defined, the third step is wiring it to the systems where your data actually lives — once, through MCP inbound connectors, rather than point-to-point per application. **Databases** — PeopleSoft, Oracle, Postgres, Snowflake — connect through the Google MCP Toolbox. **REST-based systems** — Canvas, Salesforce, Jira, ServiceNow, Workday — connect through custom MCP servers defined in `tools.yaml`. Source credentials never leave your network. Each inbound connector has isolated credential scope, with secrets encrypted at rest. The layer queries your systems in place — no records are extracted to anyone's cloud. You don't start from a blank page: ibl.ai's [AI Data Unification](https://ibl.ai/service/ai-data-unification) implementation ships with a starter catalog of 22 systems across higher education (Ellucian Banner, Slate, EAB Navigate, Handshake) and enterprise (HubSpot, Confluence, GitHub, Okta, Slack, Zendesk, Zoom). Connected data is then materialized into three knowledge layers: text memories in Markdown, a Postgres cache, and vector embeddings for semantic search — so agents can retrieve by meaning, not just keywords. The graph stays fresh on a sync schedule you control. This is the step that makes the economics compound. Connect a system once and every agent inherits scoped, governed access to it — which is [why agents built without this layer keep failing](https://ibl.ai/blog/why-ai-agents-fail-without-an-ontology) and why the tenth agent costs a fraction of the first. ## Govern It: Read-Only, Role-Scoped, Auditable The fourth step is governance — and it belongs in the build process, not after it. Three mechanisms make the ontology safe to point agents at. **Read-only enforcement.** Version 1 of the layer is read-only by design. Before provisioning, a seven-test safety suite verifies that every write attempt against your source systems is denied; if any write succeeds, provisioning halts and emits remediation SQL. Agents can read your systems — they cannot mutate them. **Identity and role scoping.** Every MCP request carries the user's Microsoft Entra ID JWT. The gateway validates it and resolves the caller's role from `roles.yaml`, so an agent sees exactly what that user is allowed to see — row-level scoping included. A teller's agent sees that teller's accounts; a clinician's agent sees that clinician's patients; an advisor's agent sees that advisor's students. Access control is consistent whether a human or an agent is asking, because agents inherit the permissions of the people they serve. **Audit as a property of the system.** Every query and every action taken through the ontology is captured as structured data. Audit trails and decision history are built in, not bolted on — a compliance answer you get by construction instead of instrumentation. ## Ship It from the CLI The fifth step is deployment — and the whole lifecycle runs from a single CLI, inside your own network. Seeding a connector from the built-in catalog is one command: ```bash ontology service add --from ``` From there, the same CLI covers service discovery and testing, schema analysis, role validation, and scheduled sync. Stand the layer up, verify each connector against its source system, confirm the role mappings resolve, and set the refresh cadence — all from your terminal. Deployment is Docker Compose: the MCP server, the Postgres cache, and the vector index all run inside your perimeter — in the cloud you choose, in your VPC, on-premise, or fully air-gapped. The implementation is open source and MIT-licensed at [github.com/iblai/ontology](https://github.com/iblai/ontology) (Python 3.11+, 163 passing tests, 85% coverage). Your engineers can read, modify, extend, or replace any part of it — there is no black box in the critical path. ## Common Mistakes When Building an Ontology The process above is straightforward; these are the four failure modes that derail it in practice. **Modeling tables instead of the world.** The most common mistake is copying database schemas into the ontology — `tbl_stu_enrl` becomes an entity type. Model what domain experts call things: students, encounters, accounts. The ontology bridges technical and non-technical teams; if it reads like a schema, it fails at that job. **Boiling the ocean.** You don't need to model the whole organization before the first agent ships. Start with a focused set of entity types for one domain — one department's decisions, one workflow — and extend as agents and users interact with the system. New modeling needs emerge organically; extend the ontology then, not before. **Skipping governance.** Teams model the nouns and verbs, then defer permissions "until production." That order is backwards: an ontology without role scoping and read-only enforcement is a data breach waiting for its first agent. Build the operational layer's permissions with the same care as the semantic layer's entities. **Renting the layer instead of owning it.** If the ontology lives inside a managed SaaS vendor's index, on their servers, under their schema, you've built the most durable asset in your AI stack — for them. The knowledge graph should be code you can read and infrastructure you run. That last mistake is the structural one. ibl.ai's [ontology framework](https://ibl.ai/ontology) is open source and self-hosted precisely so the layer you invest the most effort in is the one you own — model-agnostic, with no per-seat pricing, deployable anywhere from cloud to air-gapped. As a family-owned company operated from New York, NY, ibl.ai builds this as a long-term partner: the graph you stand up is yours to keep, extend, and govern. ## Frequently Asked Questions ### What are the steps to build an organizational ontology? Five steps: (1) model the semantic layer — entity types, attributes, relationships — in business terms; (2) model the operational layer — actions, functions, permissions; (3) connect source systems once over MCP. Then (4) govern access with read-only enforcement, identity, and role scoping; and (5) deploy from the CLI with Docker Compose inside your network. ### Do you need a formal ontology language to build one? No. The practical primitives are entity types, attributes, relationships, and actions — expressed in the vocabulary your teams already use, validated by domain experts rather than ontologists. The goal is a machine-readable map agents can reason over, not an academic artifact. ### How long does it take to build an ontology? Weeks for the first domain, not years for the whole organization. Starter connectors for 22 common systems, a CLI for discovery and testing, and Docker Compose deployment compress the setup; the modeling itself starts with one domain's core entities and grows with usage. ### Can you build and host the ontology yourself? Yes. ibl.ai's implementation is open source and MIT-licensed at github.com/iblai/ontology. It runs inside your own boundary — cloud, VPC, on-premise, or air-gapped — queries your systems in place with no data extraction, and is model-agnostic, so you own the code, the data, and the graph. --- To go deeper: the [ontology framework](https://ibl.ai/ontology) covers the modeling primitives in detail, [AI Data Unification](https://ibl.ai/service/ai-data-unification) covers the connectors and governance, [what is a data ontology](https://ibl.ai/blog/what-is-a-data-ontology) covers the concept, and [why AI agents fail without an ontology](https://ibl.ai/blog/why-ai-agents-fail-without-an-ontology) covers the case for building one first.