# How to Convert dbt MetricFlow Semantic Interface (MSI) Models to Ossie YAML Using the CLI

> Convert dbt MetricFlow Semantic Interface MSI models to Ossie YAML using the ossie convert dbt-metric-flow CLI command for streamlined data modeling.

- Repository: [The Apache Software Foundation/ossie](https://github.com/apache/ossie)
- Tags: how-to-guide
- Published: 2026-07-26

---

**Use the `ossie convert dbt-metric-flow` command to transform dbt MetricFlow Semantic Interface (MSI) JSON manifests into native Ossie YAML format, leveraging the `msi_to_osi` converter in the `converters/dbt` package.**

Apache Ossie provides a seamless migration path from dbt MetricFlow through its dedicated CLI conversion tool. This guide explains how to convert dbt MetricFlow Semantic Interface (MSI) models—typically generated as [`manifest.json`](https://github.com/apache/ossie/blob/main/manifest.json) files—into the standard Ossie YAML representation using the built-in conversion utilities located in the `converters/dbt` module.

## Prerequisites for MSI Conversion

Before running the conversion, ensure you have generated the MSI artifact from your dbt project. Run `dbt docs generate` (or the equivalent dbt-MetricFlow command) to produce the [`manifest.json`](https://github.com/apache/ossie/blob/main/manifest.json) file in your `target/` directory. This JSON file contains the complete semantic model including metrics, dimensions, and calculation expressions required for the conversion.

## Converting MSI to Ossie YAML via CLI

The conversion is handled by the **`ossie convert`** sub-command with the `dbt-metric-flow` converter type. This command delegates to the Python module `ossie_dbt.msi_to_osi` to parse the MSI structure and emit compliant Ossie YAML.

### Basic Command Structure

Execute the conversion by specifying the input MSI file and desired output path:

```bash
ossie convert dbt-metric-flow \
  --input ./target/manifest.json \
  --output ./ossie_model.yaml

```

- **`dbt-metric-flow`** selects the dbt-MetricFlow converter implementation.
- **`--input`** points to the MSI JSON file generated by dbt.
- **`--output`** specifies the destination path for the generated Ossie YAML file.

### Handling Directory Inputs

If your MSI consists of multiple files or you prefer to point to the entire dbt target directory, the converter accepts directory paths and locates the [`manifest.json`](https://github.com/apache/ossie/blob/main/manifest.json) automatically:

```bash
ossie convert dbt-metric-flow \
  --input ./target/ \
  --output ./ossie_model.yaml

```

## Core Conversion Architecture

The CLI command interfaces with several key components in the `converters/dbt` package to perform deterministic translation of dbt constructs:

- **[`converters/dbt/src/ossie_dbt/cli.py`](https://github.com/apache/ossie/blob/main/converters/dbt/src/ossie_dbt/cli.py)** — Implements the `ossie convert dbt-metric-flow` command-line interface and argument parsing.
- **[`converters/dbt/src/ossie_dbt/msi_to_osi.py`](https://github.com/apache/ossie/blob/main/converters/dbt/src/ossie_dbt/msi_to_osi.py)** — Contains the core conversion logic and the `convert_msi_to_yaml` function that maps MSI structures to Ossie YAML, translating dbt metric definitions to Ossie **Metric** and **MetricView** objects.
- **[`converters/dbt/src/ossie_dbt/expression_utils.py`](https://github.com/apache/ossie/blob/main/converters/dbt/src/ossie_dbt/expression_utils.py)** — Parses and translates dbt expression syntax into OSIE-compatible expressions during the conversion process.
- **[`converters/dbt/src/ossie_dbt/filter_utils.py`](https://github.com/apache/ossie/blob/main/converters/dbt/src/ossie_dbt/filter_utils.py)** — Provides helper utilities for handling dbt filter constructs during the transformation.
- **[`converters/dbt/src/ossie_dbt/osi_to_msi.py`](https://github.com/apache/ossie/blob/main/converters/dbt/src/ossie_dbt/osi_to_msi.py)** — Implements the reverse conversion (OSIE to MSI) primarily used for round-trip testing and validation.

## Programmatic Conversion with Python

For automated pipelines or custom scripts, you can invoke the conversion directly from Python without using the CLI:

```python
from ossie_dbt.msi_to_osi import convert_msi_to_yaml

convert_msi_to_yaml(
    input_path="target/manifest.json",
    output_path="my_model.yaml"
)

```

This approach uses the same underlying logic as the CLI command defined in [`converters/dbt/src/ossie_dbt/msi_to_osi.py`](https://github.com/apache/ossie/blob/main/converters/dbt/src/ossie_dbt/msi_to_osi.py), ensuring consistency between scripted and interactive workflows.

## Validating the Generated YAML

After conversion, verify that the output complies with the Ossie schema using the validate command:

```bash
ossie validate ./ossie_model.yaml

```

This ensures that all dbt-specific constructs have been correctly mapped to valid OSI schema elements and that the YAML file is ready for use in the Ossie ecosystem.

## Summary

- The **`ossie convert dbt-metric-flow`** command transforms dbt MetricFlow MSI models into Ossie YAML format.
- The converter accepts either a specific [`manifest.json`](https://github.com/apache/ossie/blob/main/manifest.json) file or a directory containing it via the **`--input`** parameter.
- Core conversion logic resides in **[`converters/dbt/src/ossie_dbt/msi_to_osi.py`](https://github.com/apache/ossie/blob/main/converters/dbt/src/ossie_dbt/msi_to_osi.py)**, with support from [`expression_utils.py`](https://github.com/apache/ossie/blob/main/expression_utils.py) and [`filter_utils.py`](https://github.com/apache/ossie/blob/main/filter_utils.py).
- You can use the **`convert_msi_to_yaml`** function from `ossie_dbt.msi_to_osi` for programmatic conversions in Python scripts.
- Always run **`ossie validate`** on generated files to ensure schema compliance.

## Frequently Asked Questions

### What input format does the converter expect?

The converter expects the JSON manifest file generated by dbt, typically named [`manifest.json`](https://github.com/apache/ossie/blob/main/manifest.json) and located in the `target/` directory after running `dbt docs generate`. This file contains the complete MetricFlow Semantic Interface (MSI) model including metrics, dimensions, and semantic definitions.

### Can I convert multiple MSI files at once?

Currently, the CLI processes one input path per invocation. If you have multiple MSI files, you should run the conversion command separately for each file or create a script that iterates through your dbt projects, calling `ossie convert dbt-metric-flow` with the appropriate `--input` and `--output` arguments for each manifest.

### How are dbt expressions handled during conversion?

The converter uses the **[`expression_utils.py`](https://github.com/apache/ossie/blob/main/expression_utils.py)** module located in `converters/dbt/src/ossie_dbt/` to parse dbt expression syntax and translate it into OSIE-compatible expressions. This ensures that calculated metrics and derived dimensions maintain their semantic meaning in the Ossie YAML output.

### Is there a way to convert Ossie YAML back to MSI format?

Yes, the repository includes a reverse converter in **[`converters/dbt/src/ossie_dbt/osi_to_msi.py`](https://github.com/apache/ossie/blob/main/converters/dbt/src/ossie_dbt/osi_to_msi.py)** that handles round-trip conversion from Ossie YAML back to dbt MetricFlow MSI format. This is primarily used for testing and validation purposes to ensure conversion fidelity between the two formats.