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

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 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 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:

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 automatically:

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 — Implements the ossie convert dbt-metric-flow command-line interface and argument parsing.
• 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 — Parses and translates dbt expression syntax into OSIE-compatible expressions during the conversion process.
• 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 — 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:

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, 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:

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 file or a directory containing it via the --input parameter.
• Core conversion logic resides in converters/dbt/src/ossie_dbt/msi_to_osi.py, with support from expression_utils.py and 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 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}