Table of Contents

Creating an Ontology

This guide walks you through creating an ontology from scratch - defining the business concepts in your data, mapping them to your models, and connecting them with relationships.

Ontologies are essential for MCP (Model Context Protocol) server support - they let AI agents understand your data in business terms rather than raw table and column names. For an overview of what ontologies are and why they matter, see Ontologies.

Step 1: Create the Ontology

  1. Click the Ontologies icon in the left sidebar.
  2. Click the + button next to "Ontologies."
  3. Give the ontology a name (e.g., "Customer" or "Sales").

Step 2: Select Member Models

The Member Models list shows all models in the current project. Check the models that contain data relevant to this ontology.

Only checked models are included when scanning for entities and relationships.

Step 3: Create Your First Entity

An entity is a business "noun" that has identity - something your company tracks whose records have a unique key. Customer, Product, and Invoice are entities. Sales is not - it's a measure; the entity behind it is the Invoice or Order.

The test: if its records have a key that someone could read over the phone ("Invoice 10437"), it's an entity.

Click the + button next to "Entities" and give it a name.

You can also click the scan button to let AI propose entities based on your member models. The scan presents a draft list - nothing is added until you accept it.

Setting entity details

When you select an entity, the detail panel shows:

Field What It Is
Name The business name for this concept
Definition What this concept means in business terms
Parent (level of) Set this entity's parent to build a hierarchy (see Step 4)
Synonyms Other names people use for this concept

Step 4: Build Hierarchies with Parent Entities

If the same concept exists at several levels of detail - Customer Parent, Customer Master, Customer - create each as its own entity and link them into a hierarchy using the Parent (level of) field.

To set up a hierarchy:

  1. Create each entity separately (e.g., Customer Parent, Customer Master, Customer).
  2. On the child entity, open the Parent (level of) dropdown and select the parent entity.

For example, set Customer's parent to Customer Master, and Customer Master's parent to Customer Parent. This produces the hierarchy: Customer Parent → Customer Master → Customer.

Step 5: Add Synonyms

If another system calls the same concept by a different name (e.g., your CRM calls a "Customer Master" an "Account"), add Account as a synonym on that entity. Don't create a separate Account entity.

Once you bind a level to a table, that table's name is known automatically - synonyms are for the names that aren't covered by bindings.

Step 6: Add Bindings

A binding records where an entity physically lives: which model, which table, and which column(s) serve as the identity key.

  1. Select an entity in the tree.
  2. Click + Add Binding.
  3. Choose the model, then the table, then the identity key column(s).

Rank bindings best-first - a GUID key outranks a code. The number next to each entity in the tree shows how many bindings it has.

Two bindings of one entity are the cross-model join - their key columns pair by rank. There is nothing separate to build; keep the key ranks honest and every consumer of the ontology can derive the joins.

External bindings

Click + Add External Binding to point to a table outside the current project. External bindings are not validated against a local model.

Step 7: Define Relationships

Ontology relationships connect two different concepts with a verb you supply, in subject - verb - object format (e.g., "Product - sent to → Customer Master").

  1. Scroll to the Relationships section at the bottom of the ontology view.
  2. Click + Add Relationship.
  3. Choose the subject entity, type a verb, and choose the object entity.

The AI scan proposes relationship pairs based on physical relationships in your member models, but it never writes the verb - that's always yours to supply.

Example: distinguishing two look-alike concepts

Some terms sound interchangeable but mean different things in your business. "Sales Amount" and "Revenue" are a classic case: at one company they're synonyms, at another they're distinct concepts. When they're distinct, capture that explicitly so no one conflates them.

  1. Create both as entities. Click + Add Entity and add "Sales Amount," then "Revenue."

  2. Write each one's Definition. Select the entity and fill in the Definition field. This is where the disambiguation lives:

    • Sales Amount: "Gross amount the product was sold for (price x quantity). Top-line figure; always >= 0."
    • Revenue: "Net amount actually made on the sale, after cost of sale. Can be negative (a loss). Not gross sales - see Sales Amount."

  3. Link them with a distinguishing relationship. In the Relationships section, click + Add Relationship:

    • Subject: Sales Amount
    • Verb: is distinct from (or not to be confused with)
    • Object: Revenue

  4. Save. It now renders as "Sales Amount - is distinct from → Revenue" in the entity view, the documentation export, and the Mermaid map - a visible signpost against the mix-up.

Tip

The definition does the heavy lifting - it's what an analyst reads before writing DAX. The relationship makes the distinction visible and queryable. Use this same pattern any time two terms are easily confused.

Behind the scenes, the exported JSON-LD records it like this:

"sm:entities": [
  {
    "@id": "urn:sm:entity:sales-amount:...",
    "@type": "skos:Concept",
    "rdfs:label": "Sales Amount",
    "skos:definition": "Gross amount the product was sold for (price x quantity). Top-line; always >= 0."
  },
  {
    "@id": "urn:sm:entity:revenue:...",
    "@type": "skos:Concept",
    "rdfs:label": "Revenue",
    "skos:definition": "Net amount actually made on the sale, after cost of sale. Can be negative. Not gross sales - see Sales Amount."
  }
],
"sm:predicates": [
  {
    "sm:subject": "urn:sm:entity:sales-amount:...",
    "rdfs:label": "is distinct from",
    "sm:object": "urn:sm:entity:revenue:..."
  }
]

Exporting and Importing

Right-click an ontology in the sidebar (or click the ⋮ menu) to access export and import options:

Format Use Case
XLSX / ODS Spreadsheet for review and bulk editing
JSON-LD Linked data format for integration with other systems
Turtle (.ttl) RDF serialization for semantic web tools
Documentation (HTML) Human-readable reference document
Documentation (Markdown) Markdown version of the reference document

To import, select Import... from the same menu and choose a previously exported file.

Managing Ontologies

Right-click an ontology in the sidebar for additional options:

  • Rename: Change the ontology name
  • Duplicate: Create a copy of the ontology
  • Delete: Remove the ontology entirely

Flagging for Review

Each entity has a Needs review toggle at the bottom of its detail panel. Use this to flag entities that need attention from a colleague or that you want to revisit later.

Edit this page