eMondrian Docs

Apache Ossie models

5 min read

Apache Ossie (incubating, formerly Open Semantic Interchange) is an open format for semantic models: one YAML or JSON file with datasets, fields, relationships and metrics. Snowflake, Databricks, dbt and other tools have converters for it.

An AI agent connected over MCP can write an eMondrian cube as an Ossie model (export), or build a cube from one (import). The agent does the translation; the server checks the result with validate_ossie. Available from modules 0.0.0.104 (Community 2026.11.10.1).

What you need

A key that includes MCP. The free 30-day evaluation key is enough, so you can always export your models.

Spec version

eMondrian checks against Ossie 0.3.0.dev0, a draft that will change. The JSON Schema it uses is bundled from apache/ossie (commit d700cde, 10 November 2026).

Export a cube

Ask the agent, for example:

“Read the Ossie guide, then write the Sales cube of catalog FoodMart as an Apache Ossie model. Validate it with validate_ossie and fix every error and mismatch. Give me the YAML.”

The agent reads get_ossie_guide, writes the document from the schema, and runs validate_ossie. You get the YAML or JSON text back; nothing is stored on the server.

How a cube maps to a model:

eMondrianOssie
CubeOne document
Table or ViewDataset (a view keeps its SQL as the source)
DimensionAttribute key and name columnsFields; a caption becomes its own *_name field
foreignKey / primaryKeyRelationship, from the fact (the many side)
Measure (sum, count, distinct-count, avg, min, max)Dataset metric: SUM(…), COUNT(…), COUNT(DISTINCT …), …
Calculated member: arithmetic or ratio of sum/count measuresMetric, written as a ratio of sums
Hierarchies, other calculated members, named setsThe model’s emondrian extension, or left out with a warning

An Ossie metric can’t name another metric, so calculated members are written out from their base measures. Measures that depend on the current cell — year-to-date, prior period, ParallelPeriod, set functions — have no Ossie form, and neither do sums or ratios of distinct-count or average measures.

Import a model

Put the file in the server’s share folder, or paste its text, and ask:

“Read the Ossie guide, then build a cube in catalog Shop from the Ossie model share:models/shop.yaml. Rebuild sensible hierarchies, validate the model against the cube with validate_ossie, and save the schema when every metric matches.”

The agent turns each dataset into a <View>, the datasets on the to side of relationships into dimensions, and metrics into measures. Hierarchies come from the emondrian extension if the model has one; otherwise the agent proposes them and says so. Then validate_ossie compares totals.

Converters write spec 0.2

Today’s converters in apache/ossie-converters still write spec 0.2.0.dev0, which 0.3.0.dev0 rejects. validate_ossie says so, and the guide tells the agent how to bring the document to 0.3.0.dev0.

What validate_ossie checks

validate_ossie(catalog, document, mapping?) — the document is the YAML or JSON text, or share:<path> for a file in the share. The answer has four parts:

  1. Schema — the document against Ossie’s JSON Schema.
  2. Names — keys, relationships and metrics name declared fields; no metric names another.
  3. Source — every dataset, field and metric against the catalog’s database, without reading a row.
  4. Parity — each metric’s total, in SQL the server builds from the document, against the matching measure’s total from the cube: match, MISMATCH with both totals, or not compared and why.

A metric is matched to a measure through its emondrian extension, then by name, or by the optional mapping argument: {"metric": "Cube.Measure"}.

Limits of parity:

  • It compares totals only, not totals per dimension.
  • It runs only on catalogs whose data agents may read. On a synthetic-only catalog, or under the server-wide setting, only the structure checks run — see What an agent sees of your data.
  • It reads only the tables and views the cube is built on. Table functions that reach outside the database (url, file, remote, s3, …) are refused.
  • The server builds the SQL itself; it never runs SQL the agent wrote.

What a model leaves out

An Ossie model has no hierarchies, levels, roles or row restrictions. An exported document carries no access rules: anyone who loads it into another tool gets the whole model. validate_ossie ends every answer with this note, and the agent is told to say it each time.

Also not exported: parent-child hierarchies, default members, format strings, aggregate tables and the calculated members above. Some of them are kept in the emondrian extension, which other tools ignore.

Example

A tiny export:

version: 0.3.0.dev0
name: shop_sales
datasets:
  - name: sales
    source: FACT
    fields:
      - {name: store_id, expression: {sql: STORE_ID}}
      - {name: amount, expression: {sql: AMOUNT}, datatype: Decimal}
    metrics:
      - name: amount_total
        expression: {sql: SUM(amount)}
        custom_extensions:
          - {vendor_name: emondrian, data: '{"cube": "Sales", "measure": "Amount"}'}
  - name: store
    source: STORE
    primary_key: [store_id]
    fields:
      - {name: store_id, expression: {sql: STORE_ID}}
      - {name: city, expression: {sql: CITY}}
relationships:
  - {name: sales_store, from: sales, to: store, from_columns: [store_id], to_columns: [store_id]}

validate_ossie ends with: sales.amount_total -> [Sales].[Measures].[Amount]: match, ossie 100.00, emondrian 100.0.

See also

Backlinks