Skip to content

The Semantic Layer

The Semantic Layer is what your company has written down about what its data means: which table holds revenue, whether “customers” includes trial accounts, how a fiscal year runs. The agent reads it in every Conversation that has a Data Source, so that it picks the right tables, joins and measures without your explaining them again.

The Semantic Layer is made of Context Entries. Each is one file, of one of five kinds:

  • Data Model: the tables, columns, relationships and measures of a Data Source, written in the Apache Ossie format. A Data Source has at most one.
  • Verified Query: a question and the query that answers it, whose result someone confirmed, or which was imported from Metabase. It says who confirmed it and when: whoever proposed it after confirming its result, or the reviewer who changed it. It may have parameters, such as a period or a region, so that it answers a whole family of questions.
  • Rule: how the data must be read, such as revenue leaves out cancelled orders.
  • Term: what a word of your business means in the data, such as active customer.
  • Benchmark: a known correct result, such as 12,408 orders in 2025, which the agent checks its own numbers against.

Entries other than Data Models are Markdown files in the Open Knowledge Format (OKF). An imported entry of another kind, such as a Metric or a Playbook, keeps its kind.

Each entry is linked to one or more Data Sources. It reaches the Conversations that use one of them.

You see an entry if you have access to at least one of the Data Sources it is linked to. An entry linked only to Data Sources you can’t access doesn’t exist for you: not in the Data Studio, not in an export, and not for the agent in your Conversations. Users of another Tenant never see anything of yours.

An entry whose last Data Source was deleted stays, unlinked, and only admins who manage orphaned Context Entries see it.

Entries change only through reviewed Context Change Requests. Who may propose and who may accept a change is set per Data Source with its Rights to create and to accept Context Change Requests: see Who sees a Data Source.

In a Conversation, the agent gets the list of the entries linked to the Conversation’s Data Sources, and reads the ones that bear on your question. It doesn’t see entries linked only to other Data Sources, so meanings that belong to other data don’t confuse it.

  • It writes queries from the Data Model, follows the Rules and reads your question with the Terms.
  • When a Verified Query answers your question, it runs that one, filling in its parameters, instead of writing its own, and says so.
  • It checks a number against a matching Benchmark before it gives it, and tells you when it is off.
  • It names the entries it used for an answer, by their titles, so that you can trust or challenge them.
  • When a Data Source has no entries yet, it works from the schema and says what it assumed.

What wins. Your current message comes first: ask for revenue with cancelled orders once, and you get it, and the agent points out that a Rule says otherwise. The Semantic Layer comes next, then what the agent remembers about you: when a memory contradicts an entry, the agent follows the entry and offers to delete the memory.

Changes reach the next message. When an entry changes while a Conversation is open, the agent learns it at the start of your next message, which names the entries that changed since its last answer. An answer already running doesn’t change.

The agent can’t change an entry. It can propose a change, with your Approval: see Let the agent propose a change.

Open the Data Studio from the app switcher and select Semantic Layer. The page lists the entries you may see, grouped by kind, each with its path, such as terms/active-customer.md. Filter them by Data Source or by name.

If there are no entries yet and you may propose changes, the page offers to ask the agent to model a Data Source.

Select an entry to read it. Its page shows its kind, its linked Data Sources, its content and its current version: when it was accepted, who proposed it, who accepted it and through which request. A Data Model shows Readable: its tables with their columns, the relationships and the metrics, with Find in the model to search a table or column. Switch to Ossie YAML for the file itself.

While loading, the page shows placeholders shaped like the list and the entry. It works at phone width too.

Open an entry and select the History tab. It lists every version, newest first, with whether it added or changed the entry, who proposed it, who accepted it, and the request it came through. Select a version to read it.

  • Compare versions shows the lines that differ between two versions, and how the linked Data Sources changed.
  • Revert to this version opens a Context Change Request whose content is that version, with an explanation you write. The entry changes only when someone who may accept the request accepts it, and no version is ever removed. You need the Right to create Context Change Requests on the entry’s Data Sources.

Every version of every entry is kept until your Tenant is off-boarded.

Select Export above the list. Your browser downloads semantic-layer.zip: the entries you can see, as an OKF bundle, with a generated index.md that lists them, and in each entry generated fields: entry_version, the entry’s current version, and data_sources, naming the Data Sources you can access that it links to. An import drops these two fields and keeps every other field, a version of your own too. A Data Model comes as two files, its OKF description and its .ossie.yaml model. You can import the bundle again: see Import files.

Standard Skills help you build and use the Semantic Layer. Each change any of them makes is a Context Change Request that people review.