The interviews are complete. Someone worked with the domain expert to create ontology.md. Six months later, a report counts the same Customer thrice, despite the model’s purpose to prevent this, and it hasn’t been updated since launch.

An ontology is useful only when used by a team. A software ontology is a shared model of a domain—its entities, attributes, and relationships written to ensure everyone, including code, understands each term. This guide assumes the model already exists and aims to integrate it into workflows, design, schemas, and interfaces. Select the section relevant to your task. Command examples assume PostgreSQL and psql, but they support any engine with comments and constraints. Examples refer to the Subscription Billing context from the creation guide, aligning terms across both articles.

Goal

Operate an established ontology daily to maintain it as the single source of truth for language, guide the database schema, reflect current reality, and ensure easy access.

Prerequisites

Required knowledge:

  • Comfort reading a domain model: entities, value objects, aggregates, and their relationships.
  • Familiarity with the ontology’s DDD terms: ubiquitous language, bounded context, aggregate.
  • Working knowledge of the schema or codebase the ontology describes.

Required tools:

  • The ontology in version control beside the code (e.g., ontology.md and ontology.yaml).
  • A diagram tool that renders relationships (Mermaid, PlantUML, or the native ontology editor).
  • Access to the schema migration workflow for the target database.
  • Command-line access to the database (e.g., psql) for drift check in Step 4.

Required access:

  • Write access to the repository that holds the ontology.
  • Permission to open schema migration pull requests.
  • A place to publish the ontology where the whole team can read it.

Step 1: Ground daily workflows in the ontology

Treat ontology as a dictionary that every workflow references, preventing teams from re-litigating word meanings in tickets, code reviews, and naming.

Wire it into the moments where vocabulary drifts:

  • Use exact entity names in ticket writing to avoid ambiguity. For example, specifying “let a Customer keep one Subscription after cancellation” raises the question of whether Customer means the paying account or a signed-up user, which the ontology clarifies.
  • In code review, flag new classes, tables, or API fields without matching ontology. For example, a new Account table with no Account entity indicates a name issue or missing model concept. Both are important to catch.
  • In pull request templates, add a checkbox: “New domain terms reconciled with the ontology.” It costs one line and prevents silent vocabulary forks.

Success is simple: engineers resolve ambiguous Customer references by consulting the ontology rather than relying on memory.

Step 2: Design sessions against the ontology

Design sessions introduce new concepts and influence the ontology’s growth, intentionally or unintentionally. Share the screen before starting.

Use it three ways during a session:

  • Open the bounded context to begin from agreed terms, not a blank slate.
  • As a referee, check if a proposed entity exists under another name. If the model has Subscription, a new Membership is likely the same concept. Renaming is better than creating duplicates.
  • When the session invents something new, record the term, its definition, and relationships in the ontology before the meeting ends, as notes promising to “add it later” rarely survive the week.

A practical approach for event-storming or domain-modeling is to assign one person as the ontology scribe, responsible for reconciling sticky notes with the model in real time. The scribe asks, “Does this already exist, and if not, what is it related to?” to prevent vocabulary sprawl.

Step 3: Transfer the ontology to the database schema

The ontology and schema describe the same domain at different abstraction levels. The ontology defines concepts and relations; the schema shows storage. They won’t match shape for shape, as aggregates can span multiple tables and tables can serve several concepts. The key point is that, for those familiar with the ontology, the vocabulary should be recognizable.

Carry the names and definitions with consistent rules:

flowchart TB A[Entity] --> B[Table named for the entity] C[Entity attribute] --> D[Column named for the attribute] E[One-to-many relationship] --> F[Foreign key on the many side] G[Many-to-many relationship] --> H[Join table] I[Concept definition] --> J[Column or table comment]

Apply the mapping when creating or changing a schema.

  • Name tables and columns after the ubiquitous language, not abbreviations. If it’s LineItem, use line_item, not li.
  • Carry definitions into the database by pasting the ontology’s definition on tables and columns, supported by most engines, so the meaning stays with the schema.
  • Encode relationships as constraints: “Many Invoices bill a Subscription” becomes a foreign key from invoice to subscription. A many-to-many becomes a join table. The database’s cardinality should match the model.

This migration carries an Invoice definition directly from the ontology into the schema:

CREATE TABLE invoice (
    invoice_id BIGINT PRIMARY KEY,
    subscription_id BIGINT NOT NULL REFERENCES subscription (subscription_id),
    billing_period_start DATE NOT NULL,
    billing_period_end DATE NOT NULL,
    total_cents BIGINT NOT NULL
);

COMMENT ON TABLE invoice IS
    'A demand for payment covering one billing period. Ontology: Invoice, bills exactly one Subscription.';

The subscription_id foreign key indicates “many Invoices bill a Subscription.” The comment repeats the glossary definition verbatim for clarity.

Renaming a column to match the ontology causes a breaking change, breaking all queries and views referencing the old name. Instead of a risky rename, perform three safe steps: add the new column, backfill data, migrate users, then drop the old once unused. Adding a COMMENT is reversible, but DROP or RENAME are not, so guard them with tested migrations and rollback plans.

The success check: a reader with ontology knowledge can open the schema and identify every table without a translation guide.

Step 4: Keep the ontology fresh

An ontology that stops matching reality becomes a liability, as people ignore it and document a domain that no longer exists. Freshness comes from a cadence and change, not good intentions.

Set up three habits:

  • Make ontology changes part of the work, not a follow-up. When a feature introduces a new concept, the same pull request that ships the code updates ontology.md. Reviewers block the merge if the term is missing.
  • Schedule a quarterly review to compare the ontology with the live schema, flagging nonexistent entities, changed relationships, and new concepts in the code but missing from the model.
  • Detect drift by comparing live table names with ontology entity names, highlighting missing schema elements. Run continuously to catch drift during pull requests, not months later.

This drift check reads entity names from ontology.yaml, the queryable form from the worked example, and lists tables present in the database but missing from the model.

# Tables in the database with no matching ontology entity.
# Tune the grep pattern to your ontology.yaml structure.
comm -23 \
  <(psql -Atqc "SELECT table_name FROM information_schema.tables \
      WHERE table_schema = 'public' ORDER BY table_name") \
  <(grep -oiP 'name:\s*\K\w+' ontology.yaml | tr 'A-Z' 'a-z' | sort -u)

Expected output: empty if schema and ontology match, or list of unmapped tables to reconcile. Fail CI job if list is non-empty.

The signal this is working: the latest ontology update is days old, not quarters.

Step 5: Make the ontology accessible to the team

An inaccessible ontology is useless; accessibility must be shipped, not a side effect.

Lower the cost of looking something up:

  • Publish a browsable version; busy teammates skip raw files. Create a searchable web page or wiki for easy access.
  • Make it searchable by term so that typing Subscription leads directly to its definition, attributes, and relationships, avoiding scrolling through a 200-node diagram.
  • Link to the ontology from where work happens. Add the link in README, onboarding, and pull request template. Fewer clicks between a question and answer encourage consulting the ontology instead of guessing.
  • Use it in onboarding by giving new hires the ontology as a domain map. It helps convey vocabulary faster than reading code and establishes shared language expectations.

Success is behavioral: teammates cite and link to the ontology in conversation and reviews unprompted.

Verification

Confirm the ontology is genuinely in use, not just present:

  • Open a recent pull request that introduced a domain concept. The ontology changed in the same request.
  • Pick a random table in the production schema. Its name and definition trace to an ontology entity.
  • Ask a teammate to find a domain term’s definition. They find it in under a minute by search, without asking anyone.
  • Check the ontology’s change history; the recent edit is linked to a real feature.

If all four hold, the ontology is operational.

Troubleshooting

Problem: The schema and ontology have drifted apart

Symptoms: Tables have unmatched entities or describe concepts not stored in the database.

Solution: Run a one-time reconciliation by listing all tables, columns, ontology entities, and attributes, then compare the sets. For mismatches, determine if the schema or ontology is ahead and update accordingly.

If that doesn’t work: The drift is too large to fix at once. First, use the continuous-integration drift check from Step 4 to freeze new divergence, then close the gap gradually over several sprints.

Problem: Nobody updates the ontology

Symptoms: The last edit is months old, yet the domain has clearly changed.

Solution: Integrate the update into the definition of done; a domain-touching feature isn’t complete until its pull request updates the ontology and reviewers enforce it. Process takes precedence over reminders.

If that doesn’t work: High friction; investigate causes. Formats needing special tools or unique files become outdated. Use a format everyone on the team can edit.

Problem: Two words mean the same concept

Symptoms: The ontology has Plan, but tickets, code, and sales decks all say Tier for the same thing.

Solution: Resolve in a design session (Step 2). If the two are genuinely distinct, sharpen both definitions for clarity; if they denote a single concept, adopt the ontology’s term (Plan) and update all references.

If that doesn’t work: The domain experts disagree, and the ambiguity is real. Escalate to the domain language owner and record the decision in the ontology as the tiebreaker.

Problem: The ontology is too big to navigate

Symptoms: A diagram with hundreds of entities that nobody opens.

Solution: Split by bounded context and rely on search for lookups. Most want one definition, not the whole map. Provide a search box and a relevant slice.

Related Content

References