# Apache Ossie (Open Semantic Interchange)

> Convert a Holistics AML dataset to an Apache Ossie semantic model, and an Ossie model back to AML, so your semantic layer moves with you.

## Introduction

[Apache Ossie](https://ossie.apache.org/) (formerly Open Semantic Interchange, or OSI) is an open, vendor-neutral format for exchanging semantic models between tools. A semantic model in Ossie is one YAML file with datasets, fields, metrics and relationships.

Holistics maintains an open-source converter between AML and Ossie in the Apache Ossie repository. With it you can:

- **Export** an AML dataset to an Ossie model, so any tool that reads Ossie can use your Holistics definitions.
- **Import** an Ossie model as AML files, so a model built in another tool can be brought into Holistics without rewriting it.

Holistics is listed on the [Apache Ossie ecosystem page](https://ossie.apache.org/ecosystem/).

:::info
The converter is a command-line tool that runs on your machine. It is not part of the Holistics app, and it needs no Holistics account or warehouse connection.
:::

## How it works

Understanding how AML concepts map to Apache Ossie helps you predict how your models will look after conversion. The following diagram and table show how each AML object translates to its Ossie equivalent.

<ReactFlowDiagram id="apache-ossie-conversion" height={320} fixed />

- **Export**: compile your AML dataset with the Holistics CLI, then convert it to an Ossie model. Any tool with an Ossie converter can read it.
- **Import**: convert an Ossie model, written by Holistics or by another tool, into AML files. Then validate them with the Holistics CLI.

One AML dataset becomes one Ossie model:

| In AML | In Ossie |
| --- | --- |
| The dataset | The model (document root) |
| Each model | A dataset |
| Each model dimension | A field on that dataset |
| Each model measure | A metric named `<model>__<measure>` |
| Each dataset-level metric | A metric |
| Each relationship | A relationship |

For example, this AML model:

```aml title="orders.model.aml"
Model ecommerce_orders {
  type: 'table'
  label: 'Orders'
  data_source_name: 'bigquery_demo'
  table_name: '`ecommerce`.`orders`'

  dimension id {
    label: 'Id'
    type: 'number'
    primary_key: true
  }

  dimension status {
    label: 'Status'
    type: 'text'
    definition: @sql {{ #SOURCE.status }};;
  }

  dimension delivered {
    label: 'Delivered'
    type: 'truefalse'
    definition: @aql ecommerce_orders.status == 'delivered';;
  }

  measure count_orders {
    label: 'Count Orders'
    type: 'number'
    definition: @sql {{ #SOURCE.id }};;
    aggregation_type: 'count'
  }

  measure delivered_orders {
    label: 'Delivered Orders'
    type: 'number'
    definition: @aql count(ecommerce_orders.id) | where(ecommerce_orders.delivered);;
  }
}
```

becomes this in Ossie (trimmed):

```yaml title="ecommerce.yaml"
datasets:
- name: ecommerce_orders
  source: '`ecommerce`.`orders`'
  primary_key:
  - id
  fields:
  - name: id
    expression:
      dialects:
      - dialect: BIGQUERY
        expression: id
    datatype: Decimal
  - name: status
    expression:
      dialects:
      - dialect: BIGQUERY
        expression: status
    datatype: String
  - name: delivered
    expression:
      dialects:
      - dialect: HOLISTICS_AQL
        expression: ecommerce_orders.status == 'delivered'
    datatype: Boolean
metrics:
- name: ecommerce_orders__count_orders
  expression:
    dialects:
    - dialect: BIGQUERY
      expression: COUNT(id)
- name: ecommerce_orders__delivered_orders
  expression:
    dialects:
    - dialect: HOLISTICS_AQL
      expression: count(ecommerce_orders.id) | where(ecommerce_orders.delivered)
```

- **SQL definitions** are written as SQL, tagged with your warehouse dialect.
- **AQL definitions** are kept as AQL under the `HOLISTICS_AQL` dialect. They are not translated to SQL. Another tool can read and pass them through, but only Holistics can run them.
- **Holistics-only settings** such as labels, formats and relationship options are kept in the model's `custom_extensions`. Other tools ignore them. Converting the model back to AML restores them.

## Before you start

Before converting your models, make sure you have the necessary tools installed on your local machine. You will need the Holistics CLI, Python, and the open-source converter.

- Install the [Holistics CLI](/docs/cli). It compiles AML before export and validates AML after import.
- Install Python 3.10 or later.
- Install the converter from a checkout of the Apache Ossie repository:

```bash
git clone https://github.com/apache/ossie.git
cd ossie/converters/holistics
pip install -e .
```

## Export AML to Ossie

Exporting your Holistics models to Apache Ossie is a two-step process. First, compile your AML dataset into a JSON representation, then run the converter to generate the Ossie YAML file.

1. Compile the dataset with the Holistics CLI:

   ```bash
   holistics aml compile ecommerce.dataset.aml -r . -o build/
   ```

2. Convert the compiled JSON to Ossie. Set `--sql-dialect` to your warehouse:

   ```bash
   ossie-holistics to-ossie build/ecommerce.dataset.aml.json -o ecommerce.yaml --sql-dialect BIGQUERY
   ```

## Import Ossie to AML

Import an Ossie model, written by Holistics or another tool, as AML files you can add to your project. Convert the Ossie YAML to AML, then validate it with the Holistics CLI and review the issue log.

1. Convert the Ossie model to AML files. Set `--sql-dialect` to your warehouse and `--data-source-name` to the Holistics data source the models should read from:

   ```bash
   ossie-holistics to-aml ecommerce.yaml -o aml/ --sql-dialect BIGQUERY --data-source-name my_warehouse
   ```

   This writes one dataset file and one model file per Ossie dataset.

2. Validate the result with the Holistics CLI:

   ```bash
   holistics aml validate aml/ecommerce.dataset.aml -r aml/
   ```

3. Review the files and the issue log, then add them to your Holistics project.

Ossie metrics that span several datasets are written as AQL metrics on the dataset, since that is where AML defines cross-model metrics.

## Options

The converter supports several command-line options to customize the import and export process. Use these options to set the output path, your warehouse's SQL dialect, the Holistics data source and where the issue log goes.

| Option | Used with | What it does |
| --- | --- | --- |
| `-o` | both | Required. An output file for `to-ossie`, an output directory for `to-aml`. |
| `--sql-dialect` | both | Required. `ANSI_SQL`, `OSSIE_SQL_2026`, `BIGQUERY`, `DATABRICKS` or `SNOWFLAKE`. |
| `--data-source-name` | `to-aml` | The Holistics data source for the generated models. Required unless the Ossie model came from Holistics. |
| `--issues FILE` | both | Write the issue log to a file instead of the terminal. |
| `--force` | both | Overwrite existing output files. |

## Issues

Every conversion reports what it dropped or changed, with a severity:

- **INFO**: something was kept in another form, for example an AQL definition carried as `HOLISTICS_AQL`.
- **WARNING**: something was dropped or changed, for example a relationship filter that Ossie cannot express.
- **ERROR**: something could not be converted, for example a query model that uses Holistics template syntax.

The command exits with code `1` when any ERROR is reported, so you can run it in CI.

## What does not convert

Some Holistics features have no Ossie equivalent. The table shows what happens to each, both in the Ossie model and when you convert it back to AML.

| In Holistics | What happens |
| --- | --- |
| Query models using template syntax (`{{ #model }}`, `{% filter() %}`) | ERROR. The SQL is kept unresolved, so other tools cannot run it. |
| Range and many-to-many relationships | WARNING. Kept for the round trip. Other tools see the two datasets as unrelated. |
| Inactive relationships | WARNING. Ossie has no way to mark them inactive, so other tools join across them. |
| Relationship filters (`where`) | WARNING. Other tools join without the filter. |
| Params | WARNING. Kept for the round trip, not usable by other tools. |
| Window functions in Ossie metrics (import) | ERROR. The metric is dropped. |
| Dashboards, reports and canvases | Not converted. Ossie describes the semantic model only. |
| Comments and file layout | Not kept. A round trip returns the same models, not the same files. |

The full list, with every issue code, is in the converter's [limitations](https://github.com/apache/ossie/blob/main/converters/holistics/docs/limitations.md).

## Related

- [Open Semantic Layer](/docs/open-semantic-layer)
- [Holistics CLI](/docs/cli)
- [Converter source and documentation](https://github.com/apache/ossie/tree/main/converters/holistics)