Skip to content

Semantic Models

Describe the datasets, fields, metrics and relationships that BI tools and AI agents query, in the open Apache Ossie format, and link each element to the business concepts of your ontology.

A semantic model is the layer between physical tables and the people or agents that ask questions of them. It says which tables exist, how they join, which columns are dimensions and which are facts, and how a metric such as Total Revenue is calculated. Entropy Data stores each semantic model as an Apache Ossie document, so the same file can move between Entropy Data, BI tools and AI agents.

A semantic model is different from a Semantics namespace. A namespace is the ontology: it defines what a Customer or Revenue means, independent of any system. A semantic model describes concrete datasets and points each of their elements at a concept in the ontology.

The semantic model page: header with the Ossie mark, metrics with their formulas, and the first dataset with its fields and links to the ontology

Enable Semantic Models

Semantic models are part of the Semantics feature and have no switch of their own. Semantics is on by default.

  • Entropy Data Cloud: semantic models are available in every organization that has Semantics.
  • Self-Hosted: semantic models are available unless you turned Semantics off with application.semantics.enabled=false (environment variable APPLICATION_SEMANTICS_ENABLED=false).

Where Semantic Models Appear

The Semantics Overview

Open Semantics in the sidebar of the Marketplace or the Studio. The overview lists the ontology namespaces first and the semantic models below them. For each semantic model, the table shows the owner team, the data product, the number of datasets and metrics, the number of elements linked to the ontology, and the number of open branches.

The Semantics overview with the namespaces and the Semantic Models table below them

The Data Product Page

A data product has at most one semantic model. When it has one, the data product page shows a Semantic Model section with the model in a condensed form: the metrics, a list of datasets that you can expand to their fields, and the relationships. In the Marketplace, the section is read-only. In the Studio, it also has the actions to edit the model.

The Semantic Model section on the Customer Revenue data product page

The built-in data product type Semantic Model is for a data product whose main output is a semantic model. You can still attach a semantic model to a data product of any other type.

Other Places

  • Search: global search finds semantic models by their name and by the names and descriptions of their datasets, fields, relationships and metrics.
  • Concept pages: the page of a concept in a Semantics namespace lists the semantic models that link to it.
  • Assets: the page of a Power BI semantic model asset or a Snowflake semantic view asset shows the semantic model that the source tool defines, and links to the Entropy Data semantic model created from it.
  • Entropy Intelligence: the chat can search semantic models and read one, with its datasets, metrics and formulas, relationships, linked concepts, data product and lineage. See Entropy Intelligence.

The Semantic Model Page

The page of a semantic model has a header, a main column and a sidebar.

The header shows the Ossie mark, the name and the ID of the model, and below them the owner team, domain, status and tags. On the right are the Branch switcher, the Actions menu and the Edit button. The Actions menu offers Create Data Contract and, for a model without a data product, Create Data Product.

The main column shows, from top to bottom:

  1. Description, and the concepts linked to the model as a whole.
  2. Metrics: name, data type, description, linked concepts and formula of each metric.
  3. One card for each dataset: the name, the number of fields, the linked concept, the description, the unique keys and the synonyms. A table lists the fields with their data type, description, linked concept and formula. The formula appears only for a calculated field.
  4. Relationships: each join, with the datasets and columns on both sides and the linked concept.

A dataset card with its fields, their roles, data types, links to the ontology and formulas

The Relationships card: ORDERS joins CUSTOMERS on customer_id, linked to the Order.placed_by relationship of the ontology

A glyph in front of each field shows its role. Ossie has no field roles, so Entropy Data derives them from the document:

  • Key column (key icon): the field is part of the primary key, a unique key or a relationship.
  • Dimension (◇): the field has a dimension block, or its data type is not numeric.
  • Time dimension (◷): the field has dimension.is_time: true.
  • Fact (#): the data type is Integer, Decimal or Float.
  • Calculated (small ƒ next to the role): the expression is more than the name of a column, for example LOWER(email).

A metric that reads from one dataset only is also listed in the card of that dataset, so the card shows everything that you can calculate from that table.

The sidebar shows the Data Product that offers the semantic model. If the model was imported from an asset, the sidebar also shows a Source card. See Imported Semantic Models and Drift.

Create a Semantic Model

You can create a semantic model in four ways.

From the Semantics Overview

  1. Open Studio > Semantics.
  2. Click Add Semantic Model.
  3. Choose Add in the Editor to start in the visual editor, or Add as YAML to paste or write an Ossie document.

The Add Semantic Model menu with Add in the Editor and Add as YAML

The new model starts from a template. The template sets the Ossie version, a placeholder name, the status draft, and the first team in which you can add semantic models as the owner. The template has no datasets. Add at least one dataset before you save, because the Ossie schema requires one.

From a Data Product

Open a data product in the Studio that has no semantic model yet. Choose Add Semantic Model and then Add in the Editor or Add as YAML. The new model already names the data product. To give a semantic model to a data product, you must have the edit permission on that data product.

From an Asset

Entropy Data converts two kinds of assets into Ossie semantic models:

  • Power BI semantic models (asset type powerbi_semantic_model), read from their TMDL definition. Tables become datasets, columns become fields, and measures become metrics. Measures keep their DAX expressions in the DAX dialect.
  • Snowflake semantic views (asset type snowflake_semantic_view), read from their Cortex Analyst YAML. Logical tables become datasets. Dimensions, time dimensions and facts become fields. Metrics and derived metrics become metrics in the SNOWFLAKE dialect.

Information that Ossie cannot express goes into a POWER_BI or SNOWFLAKE custom extension, so nothing is lost.

To convert an asset, open the asset in the Studio and choose Create > Create Semantic Model. The new model belongs to the team that owns the asset and to no data product. If the asset already has a semantic model, the menu shows Open Semantic Model instead.

A Power BI semantic model asset. The Create menu holds Create Semantic Model, and the Semantic Model section shows the model as the source tool defines it

When You Import a Data Product from an Asset

When you import a data product from a Power BI semantic model or a Snowflake semantic view, Entropy Data also creates the semantic model and gives it to the new data product. If the conversion fails, the data product is still imported, without a semantic model.

The Semantic Model Editor

Click Edit on the semantic model page to open the visual editor. The editor has two views, Editor and YAML, that edit the same document. Switch between them at any time.

The semantic model editor: the diagram of the datasets at the top, the element tree on the left and the model overview on the right

The Editor view has three parts:

  • Diagram: the datasets as tables, with their fields and the relationships between them. To create a relationship, drag a field onto a field of another dataset. Use the controls on the left to zoom and fit the diagram, and the arrow below it to fold it away.
  • Element tree on the left: Overview, Sources, Metrics and Datasets with their fields. Click + next to a group to add a source, a metric or a dataset. Click an element to edit it.
  • Form on the right: the fields of the selected element. The Overview form edits the name, version, description, linked concepts and AI context of the whole model. A counter above it shows the number of datasets, dimensions, facts, metrics and relationships.

Edit Fields and Metrics

Select a field to edit its name, data type, role and expression. Under Role, choose By datatype to let the data type decide, or set Dimension or Time dimension explicitly.

The expression editor checks the expression as you type and shows, for example, Valid ANSI SQL. Click + Dialect to add the same expression in another SQL dialect, such as Snowflake, Databricks or DAX. The Functions panel on the right lists the functions for the current dialect, grouped by kind. Click a function to insert it. Drag a field from the tree into the expression to insert its name.

Editing the calculated field full_name: role, ANSI SQL expression and the function palette

Metrics are edited the same way. A metric expression aggregates over a dataset, for example SUM(ORDERS.amount), so the function palette starts with the aggregates.

Editing the metric total_revenue, linked to the Revenue concept of the finance namespace

Every dataset, field, relationship and metric, and the model itself, has a Semantics block. Click Link concept to pick a concept or a relationship from a Semantics namespace. A field usually links to a property of the concept that its dataset represents, for example CUSTOMERS.email to Customer.email.

These links make the semantic model readable for people and agents that know the business terms but not the table names. They also appear on the page of the concept, so you can see which semantic models implement it.

AI Context

Expand AI context on any element to give AI tools more to work with:

  • Instructions: how to use the element, for example "Use this model for customer and revenue analysis".
  • Synonyms: other names for the element, separated by commas.
  • Example questions: questions that the element can answer.

YAML View and Validation

The YAML view shows the whole Ossie document, with comments kept. The Problems bar at the bottom checks the document against the Ossie schema while you type. Validation in the header shows a check mark when there are no problems, or the number of problems.

The YAML view of the editor with the Problems bar

Click Save to save the model. If someone else saved the model while you edited it, Entropy Data does not overwrite their change. Reload the editor and apply your change again. Delete deletes the whole semantic model.

The Ossie Document

A semantic model is one YAML document in the Apache Ossie Core Metadata format, version 0.2.0.dev0. The document can be read and written with the YAML view, the API and the MCP tools.

Example

This example has two datasets, one relationship and one metric. The ENTROPY_DATA custom extensions hold the Entropy Data metadata and the links to the ontology.

version: "0.2.0.dev0"
name: "crm"
description: "Customers and their orders"
custom_extensions:
  - vendor_name: "ENTROPY_DATA"
    data: '{"id": "crm", "dataProduct": "customer-revenue", "owner": "sales-team", "status": "active"}'
ai_context:
  instructions: "Use this model for customer and revenue analysis"
datasets:
  - name: "CUSTOMERS"
    source: "crm.public.customers"
    primary_key: ["customer_id"]
    description: "One row per customer"
    custom_extensions:
      - vendor_name: "ENTROPY_DATA"
        data: '{"semantics": [{"concept": "crm:Customer"}]}'
    fields:
      - name: "customer_id"
        expression:
          dialects:
            - dialect: "ANSI_SQL"
              expression: "customer_id"
        datatype: "String"
      - name: "email"
        expression:
          dialects:
            - dialect: "ANSI_SQL"
              expression: "LOWER(email)"
        datatype: "String"
        custom_extensions:
          - vendor_name: "ENTROPY_DATA"
            data: '{"semantics": [{"relationship": "crm:Customer.email"}], "relationship_type": "hasProperty"}'
  - name: "ORDERS"
    source: "crm.public.orders"
    primary_key: ["order_id"]
    fields:
      - name: "order_id"
        expression:
          dialects:
            - dialect: "ANSI_SQL"
              expression: "order_id"
        datatype: "String"
      - name: "customer_id"
        expression:
          dialects:
            - dialect: "ANSI_SQL"
              expression: "customer_id"
        datatype: "String"
      - name: "order_date"
        expression:
          dialects:
            - dialect: "ANSI_SQL"
              expression: "order_date"
        datatype: "Date"
        dimension:
          is_time: true
      - name: "amount"
        expression:
          dialects:
            - dialect: "ANSI_SQL"
              expression: "order_total"
        datatype: "Decimal"
relationships:
  - name: "orders_to_customers"
    from: "ORDERS"
    to: "CUSTOMERS"
    from_columns: ["customer_id"]
    to_columns: ["customer_id"]
metrics:
  - name: "total_revenue"
    expression:
      dialects:
        - dialect: "ANSI_SQL"
          expression: "SUM(ORDERS.amount)"
    description: "Total revenue from all orders"
    datatype: "Decimal"
    custom_extensions:
      - vendor_name: "ENTROPY_DATA"
        data: '{"semantics": [{"concept": "finance:Revenue"}]}'

Structure

ElementRequired keysOptional keys
Documentversion, name, datasets (at least one)description, ai_context, relationships, metrics, custom_extensions
Datasetname, sourceprimary_key, unique_keys, description, ai_context, fields, custom_extensions
Fieldname, expressiondatatype, dimension (with is_time), label, description, ai_context, custom_extensions
Relationshipname, from, to, from_columns, to_columnsai_context, custom_extensions
Metricname, expressiondatatype, description, ai_context, custom_extensions

Keys that the schema does not know are refused.

  • An expression holds a list of dialects, each with a dialect and an expression. The dialects are ANSI_SQL, SNOWFLAKE, DATABRICKS, BIGQUERY, DAX, MDX, TABLEAU, MAQL, SIGMA, THOUGHTSPOT and OSSIE_SQL_2026.
  • A datatype is one of String, Integer, Decimal, Float, Boolean, Date, Time, DateTime, DateTimeTz and Opaque.
  • ai_context is a string, or an object with instructions, synonyms and examples.
  • A custom extension has a vendor_name and a data string.

The Entropy Data Extension

Entropy Data reads the custom extension with vendor_name: "ENTROPY_DATA". Its data is a JSON object written as a string.

On the document, the extension holds the metadata of the semantic model:

KeyMeaning
idThe ID of the semantic model in Entropy Data. If it is missing, Entropy Data derives the ID from name. The ID cannot change after the first save.
dataProductThe ID of the data product that offers the model.
ownerThe ID of the owner team.
domainThe ID of the domain.
statusThe status, for example draft or active.
tagsA list of tags.
semanticsLinks of the whole model to the ontology.

On a dataset, field, relationship or metric, the extension holds the links of that element:

  • {"concept": "crm:Customer"} links to a concept, written as namespace:ConceptId or as the IRI of the concept.
  • {"relationship": "crm:Customer.email"} links to a relationship or property of a concept, written as namespace:Concept.property or as an IRI. Add "role": "Country" to name the target of a relationship that has more than one role.
  • relationship_type is optional and records the type of the relationship, for example hasProperty or relatedTo.

When the ontology changes, Entropy Data checks the links again. The model itself does not change.

Validation

Entropy Data refuses to save a document with one of these errors:

  • The YAML is not valid, or the document does not match the Ossie schema.
  • The Ossie version is not supported.
  • Two datasets, two fields of one dataset, or two metrics have the same name.
  • A relationship names a dataset that does not exist, or its from_columns and to_columns have different lengths.
  • The ENTROPY_DATA extension occurs twice on one element, its data is not valid JSON, or its structure is not valid.
  • The ID changed, contains one of the characters / \ % ; # ?, or is already used by another semantic model.
  • The owner team does not exist, or someone other than an organization owner removed it.
  • A tag is not one of the managed tags of the organization.
  • The data product already has another semantic model.

Entropy Data saves the document but shows a warning when the data product or the domain does not exist, or when a link to the ontology cannot be resolved. Fix a warning later, for example after you add the missing concept.

Data Products and Data Contracts

The Data Product of a Semantic Model

The dataProduct key gives a semantic model to a data product. A data product has at most one semantic model. To give a model to a data product, move it to another one, or take it away, you need the edit permission on each data product involved. When a data product is deleted, its semantic model stays and belongs to no data product.

A reader who is not allowed to see the data product sees the semantic model, but not the name of the data product.

Create a Data Contract from a Semantic Model

Choose Actions > Create Data Contract on the semantic model page. On an output port that has no data contract and no assets, the data product page also offers Create Data Contract from Semantic Model.

Entropy Data opens the data contract editor with an ODCS contract drafted from the model:

  • one schema object for each dataset, with the source as the physical name,
  • one property for each field, with its logical type, description and primary key,
  • the links to the ontology as semantics authoritative definitions,
  • the relationships as foreign keys.

Metrics are not part of the contract. Nothing is saved until you save the contract in the editor.

Create a Data Product from a Semantic Model

A semantic model without a data product, for example one converted from an asset, offers Create Data Product in the Actions menu and in the sidebar. Entropy Data opens the form for a new data product. When you create the data product, Entropy Data gives the semantic model to it. If the data product needs approval first, the model is given to it after the approval.

Imported Semantic Models and Drift

A semantic model converted from a Power BI semantic model or a Snowflake semantic view remembers its source asset. The header names the source tool, and the sidebar shows the Source card.

A semantic model imported from Power BI: DAX formulas in the metrics, and the Source card that reports no drift

The Source card compares the semantic model with its source. Entropy Data converts the asset again and compares the two element by element. Its own additions, such as the name and the ENTROPY_DATA extensions, do not count.

  • No drift detected (Passed): the model matches its source.
  • Drift detected (Drift): the model and the source differ. The card lists each difference as Only in the model, Only in the source or Different.
  • Drift unknown (Unknown): the source asset no longer exists, or it cannot be converted.

Entropy Data does not change the semantic model when its source changes. To take over a change from the source, edit the model.

Branches

A branch is a working copy of a semantic model. Use a branch to draft a larger change, to let a colleague or an agent propose one, or to review a set of edits before they change the model. Nothing on a branch is visible outside it until you merge it.

Create a Branch

  1. On the semantic model page, open the Branch switcher.
  2. Choose New branch.
  3. Enter a name that says what the work is about, for example add-average-order-value. Spaces become hyphens. Only letters, digits and ., _ and - are kept. The names main and new are reserved.
  4. Click Create branch.

The New branch form with the existing branches of the model

Work on a Branch

The branch page shows a band: You are on branch add-average-order-value of crm, with the number of changes. The Model tab shows the model as it is on the branch. Each element that the branch adds, edits or removes carries a mark.

A branch of the crm model: the band with Merge to main and Actions, and the Model tab

Use Edit > Edit in the editor or Edit > Edit YAML to change the branch. A branch cannot change the ID, the owner team or the data product of the model.

The Changes tab lists every change of the branch, compared with the semantic model as it is now. Each change shows whether an element was Added, Edited or Removed, the old and the new value, and its impact:

  • Structural: a change that alters query results, such as the source, a key, an expression, a data type, a dimension, or the datasets and columns of a relationship.
  • Descriptive: a change to a description or another field that does not alter query results.

The Changes tab: two descriptive edits and one structural addition, with main and the branch side by side

Update from Main and Resolve Conflicts

If the semantic model changed after you created the branch, choose Actions > Update from main to take those changes into the branch. Entropy Data merges the model, the branch and their common starting point element by element.

If the model and the branch changed the same element, the branch is marked Conflicted. A conflict occurs when an element changed on both sides, changed on one side and was removed on the other, or was added on both sides with different content. Click Resolve conflicts to see both versions side by side. Choose per element, or choose Use this branch for all or Use main for all.

Merge a Branch

Click Merge to main and confirm. Every change of the branch lands on the semantic model, and the branch is deleted. The merge saves the model with the same checks as any other save. You cannot merge a branch that has conflicts or no changes.

Actions > Delete branch discards the branch without merging it.

Permissions

Every member of the organization can see semantic models. The owner team of a semantic model controls who can change it:

ActionRequired permission
Create a semantic modelSEMANTICMODEL_ADD on the owner team.
Edit a semantic modelSEMANTICMODEL_EDIT on the owner team. Without an owner team, SEMANTICMODEL_ADD in any team.
Delete a semantic modelSEMANTICMODEL_DELETE on the owner team. Without an owner team, organization owners only.
Create and edit a branchSEMANTICMODEL_EDIT or SEMANTICMODEL_BRANCH_ADD on the owner team.
Merge a branchSEMANTICMODEL_EDIT on the owner team.
Delete a branchThe permission to merge, or the person who created the branch.
Give a model to a data productAlso DATAPRODUCT_EDIT on the data product.

The default team roles Owner, Approver and Editor can add, edit and delete semantic models. The Member role has SEMANTICMODEL_BRANCH_ADD only, so a member can propose a change on a branch, and an editor merges it.

API keys and agents follow the same permissions. See Roles.

API and MCP

REST API

The semantic models API is under /api/semanticmodels. See the API reference for the full description.

MethodPathDescription
GET/api/semanticmodelsList semantic models, 1000 per page.
GET/api/semanticmodels/{id}Read a semantic model as JSON.
GET/api/semanticmodels/{id}/semantic_model.yamlRead the original YAML document, with comments.
PUT/api/semanticmodels/{id}Create or replace a semantic model. The response lists the warnings.
DELETE/api/semanticmodels/{id}Delete a semantic model.
GET, POST/api/semanticmodels/{id}/branchesList the branches, or create one.
GET, DELETE/api/semanticmodels/{id}/branches/{branch}Read or delete a branch.
GET, PUT/api/semanticmodels/{id}/branches/{branch}/documentRead or replace the document of a branch.
GET/api/semanticmodels/{id}/branches/{branch}/changesList the changes of a branch.
GET/api/semanticmodels/{id}/branches/{branch}/conflictsList the conflicts of a branch.
POST/api/semanticmodels/{id}/branches/{branch}/rebaseUpdate a branch from main, with optional resolutions.
POST/api/semanticmodels/{id}/branches/{branch}/mergeMerge a branch.

Saving a semantic model publishes the events SemanticModelCreatedEvent, SemanticModelUpdatedEvent and SemanticModelDeletedEvent to the event feed, but only when the document changed.

MCP Tools

AI agents work with semantic models through the MCP server:

ToolDescription
semanticmodel_listFind semantic models, with an optional search query.
semanticmodel_getRead a semantic model, or one of its branches, as YAML.
semanticmodel_saveCreate or replace a semantic model, or write to a branch.
semanticmodel_create_branchCreate a branch of a semantic model.
semanticmodel_list_branchesList the branches of a semantic model.
semanticmodel_get_branch_changesList the changes of a branch.

An agent cannot merge a branch. A person reviews the branch and merges it in the UI, so an agent can propose a change without changing the model directly.