How to Read an Apache Ossie Model: From YAML File to Diagram

The 30-second version: paste a link, see the model

The OWOX Model Canvas at model.owox.com is free and needs no login. It opens an Ossie file straight from GitHub if you put the file’s address after ?ossie=:

https://model.owox.com/?ossie=https://github.com/apache/ossie/blob/main/examples/tpcds_semantic_model.yaml

Open that link and an import dialog appears with the model already read. Before you click anything it lists the datasets and their field counts, anything it will not import, any warnings, and a closing line: “Will import 5 marts, 4 relationships.” Clicking Import puts the model on the canvas. If the canvas already holds a model, the dialog first asks whether to replace it or merge the new file into it, so open a file on a blank canvas when you only want to look at it.

Anatomy of an Ossie file

The 0.2.0.dev0 specification says each document describes exactly one semantic model, and requires three things at the root: version, name and a non-empty datasets list. Everything else is optional. The TPC-DS example uses all of it:

Files written before this draft look different. Earlier versions wrap the model in a semantic_model list, and the current schema does not accept that wrapper. The canvas read a small file in the old shape without complaint, but the repository’s own validator refused it with four errors, among them “‘version’: ‘0.2.0.dev0’ was expected” and “Additional properties are not allowed (‘semantic_model’ was unexpected)”. The canvas is forgiving where the schema is not.

The last key deserves a note. custom_extensions is how a vendor stores its own data in a shared file: each entry has a vendor_name and a data string, and the TPC-DS example carries one for SALESFORCE and one for DBT. The spec calls them vendor-specific attributes, and its migration notes say to preserve custom extensions when a file moves between shapes. The canvas does not carry the SALESFORCE and DBT entries over, which is why both show up under “Not imported”, and it writes its own OWOX entry in their place.

Read the TPC-DS example, dataset by dataset

The model has a fact table, store_sales, and four dimensions: date_dim, customer, item and store. The canvas reports 17 fields on store_sales and 5 to 6 on each dimension, so it is clear at once where the weight is.

The 17 needs explaining, because the file does not declare 17 fields on store_sales. It declares nine. The other eight are the model’s metrics, which the canvas places on store_sales as calculated fields, and an export to OKF lists them under “Calculated fields” on that page. A metric always has to live on some dataset, and the canvas picks the one the formulas read from.

Switch to the view that shows fields and you can read the keys too. store_sales declares a composite key:

- name: store_sales
  source: tpcds.public.store_sales
  primary_key: [ss_item_sk, ss_ticket_number]

and the canvas draws a key icon next to both columns.

That is the fields view; the dimension cards below it carry the same icons. On each dimension the key is a single surrogate column such as d_date_sk or i_item_sk. One thing the canvas did not carry over: the customer dataset also declares unique_keys: [c_customer_id], and the import dialog lists it under “Not imported”.

Relationships: reading the join

A relationship is a from dataset, a to dataset and the key columns on each side:

- name: store_sales_to_item
  from: store_sales
  to: item
  from_columns: [ss_item_sk]
  to_columns: [i_item_sk]

On the canvas it is a line from store_sales to item, labelled ss_item_sk = i_item_sk and marked N:1. Select the line and the Inspect panel shows the same key pair, a description taken from the file’s synonyms, and a cardinality field that reads “Optional – for modeling/visualization only.”

The TPC-DS file states no cardinality. The N:1 on the line is what the canvas shows, and on export it keeps that value in an OWOX extension. Worth knowing before you quote a cardinality from a diagram as if the file said it.

Metrics and calculated fields

In the file a metric is an expression written against dataset names, not table names:

- name: total_sales
  expression:
    dialects:
      - dialect: ANSI_SQL
        expression: SUM(store_sales.ss_ext_sales_price)

On the canvas, the same definition is a calculated field on store_sales, and its formula drops the dataset prefix: SUM(ss_ext_sales_price). A formula that reads from another dataset keeps the prefix. customer_lifetime_value, for example, divides by COUNT(DISTINCT customer.c_customer_sk).

Three of the eight metrics are window functions: cumulative_sales, brand_rank_in_store and monthly_sales_change. The canvas imported all three and warned that OWOX does not support window functions and would refuse them on push. That is a limit of the target, not a fault in the file, and the warning is how you find out before you push.

Dialects and AI context

Every field and metric carries a list of dialects. In TPC-DS each has one, ANSI_SQL. A file can list several, such as ANSI_SQL and SNOWFLAKE, and each tool decides which entry it reads. The Snowflake documentation says its converter uses the SNOWFLAKE or ANSI_SQL entry and skips a field that has neither, without an error. Check which dialects your file actually carries before you trust a count of what loaded.

ai_context is where the file talks to an AI agent: instructions on the model, and synonyms on datasets, fields, metrics and relationships. total_sales lists “total revenue”, “gross sales” and “sales amount”. On the canvas that text arrives appended to the description as a line starting “Synonyms:”, and the diagram does not treat it as structure. On export the structured ai_context does not come back: 25 field-level blocks in the original are gone from the exported file, folded into description text.

When a file will not open

Flights is the better lesson, because it is three documents. The repository’s examples/ folder has flights.semantic_model.yaml, flights.ontology.yaml and flights.mapping.yaml, and the canvas opens only the first:

• The semantic model opened as six datasets – RUNWAY with 4 fields, AIRCRAFT 9, AIRPORT 9, FLIGHT 21, CARRIER 2 and ROUTE 6 – and “0 relationships”. The file declares none. The joins are in the other documents.

• The ontology was refused with: “This is an Apache Ossie ontology (business concepts), not a semantic model. The canvas imports semantic models: import the file with a top-level “datasets” list instead.”
• The mapping was refused with: “This is an Apache Ossie mapping document, not a semantic model. Import the semantic model it points to instead: ./flights.semantic_model.yaml”

Two more cases we tried by pasting a file in. A broken line got a plain parse error with the line and column (“Flow sequence in block collection must be sufficiently indented and end with a ] at line 5, column 30”). A relationship that names a dataset the file does not declare was dropped: “Will import 1 marts, 0 relationships”, with one item under “Not imported”. Read that second line before you click, because the import is otherwise silent about it. The rule we took from these runs is simple: look at “Not imported” and the warnings before you press Import, not after.

Validate and share

Opening a file is not validating it. The repository ships validation/validate.py, which checks the JSON Schema, unique names, relationship references, key counts and SQL syntax. We ran it on four files and all four passed: the TPC-DS original, the Flights semantic model, the TPC-DS file after a round trip through the canvas, and the canvas’s export of its E-commerce template. The last one passed with a warning: a relationship whose target columns do not cover the target dataset’s primary or unique key.

The round trip changed more than the check shows. Exporting TPC-DS back to Apache Ossie gave a file that validates, with the same five datasets, four relationships and eight metrics, and the same version string, 0.2.0.dev0. It also gave a file of 519 lines against 672 and these differences:

• the 26 field-level dimension blocks are gone;
• the unique_keys are gone: all five datasets declare them, and each declaration repeats the dataset’s primary key, apart from customer’s second key, c_customer_id, which is the one the import dialog lists under “Not imported”;
• structured ai_context is flattened into description text;
• the SALESFORCE and DBT extensions are replaced by a single OWOX extension;
• relationships were renamed, store_sales_to_date becoming store_sales_to_date_dim.

A second model showed one more change. We wrote a small revenue model (two datasets, one relationship, three metrics) and left datatype off the fields. After the round trip every field was typed String, including order_date, line_revenue and line_net_revenue, and each of the three metrics gained Decimal. The OKF export showed the same: the schema table lists line_revenue as STRING. If your file leaves types out, the canvas fills them in, and the filled-in values are guesses. The specification says to omit datatype when the type is unknown, so the guess goes against its own guidance. The one dimension block in that model, is_time: true on order_date, was dropped as well.

None of this breaks the file, and all of it matters if the exported copy is the one another tool will read. Export from the canvas to look at a model, not to replace the original.

A checklist for reviewing an Ossie file

From these runs, in the order we would do them:

1. Read the version first. 0.2.0.dev0 and 0.1.1 are different shapes, and the tools that read the file name the version they accept.
2. Open it, then read “Not imported” and the warnings before you import. They are the cheapest list of what a tool cannot act on.
3. Count. Datasets, relationships and metrics in the dialog should match what you expect from the file. A relationship that names a dataset the file does not declare disappears from the count without an error.
4. Find where each metric lives. A metric sits on one dataset, and its formula may read from others through relationships. Check that the relationships it needs exist.
5. Check the dialects. Make sure every field and metric carries an entry the tool you care about reads.
6. Run validate.py on the file, and on the ontology with --schema ontology/ontology.json if you have one. The Flights ontology passes under its own schema, and the Flights semantic model passes under the default one.
7. After any export, diff it against the original. Types, dimension blocks, unique_keys and structured ai_context are the places it will differ.

The export menu also offers PNG and SVG, so the diagram itself can go into a review thread. The OKF vs Ossie comparison shows what the same model looks like in Google’s format, and the Model Canvas is where to try your own file.

Data ModelingWhat Is Apache Ossie? The Open Standard for Semantic Models, ExplainedOctober 19, 2026→Data ModelingBenefits of Data Modeling for Business ReportingMarch 3, 2025→Data ModelingBest Data Modeling Tools in 2026July 21, 2026→

See all articles →