# How to Translate Between Ossie and Other Semantic Model Formats (OBML, Snowflake, GoodData, DBT)

> Easily translate between Ossie and other semantic model formats like OBML, Snowflake, GoodData, and DBT. Use bidirectional converters with CLI commands and Python APIs for lossless conversions.

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

---

**You can translate between Ossie and other semantic model formats using the bidirectional converters in the `converters/` directory, which provide both CLI commands and Python APIs for lossless round-trip conversions.**

The **apache/ossie** repository provides a complete toolkit for semantic model interchange. OSSIE (Open Semantic Interchange Engine) stores all semantic models in a canonical **OSI core-spec** representation, making it possible to translate between Ossie and other semantic model formats through standardized converter modules.

## Overview of Ossie Format Converters

All format-specific converters reside under the **`converters/`** directory in the repository root. Each converter implements bidirectional transformation between the OSI model and a target format, ensuring that datasets, fields, measures, dimensions, and relationships map accurately across ecosystems.

The following converter modules are available:

- **orionbelt** – Translates between OSI and OBML (OrionBelt Markup Language)
- **snowflake** – Converts OSI to Snowflake YAML semantic models and vice versa  
- **gooddata** – Handles OSI ↔ GoodData JSON model transformations
- **dbt** – Transforms OSI to dbt MSI (Metric Semantic Interface) models

Each module exposes both a **CLI entry point** (e.g., `ossie-snowflake`) and a **Python API** (e.g., `from ossie_snowflake import OSIToSnowflakeYAML`), providing flexibility for automation scripts and CI/CD pipelines.

## Supported Converter Modules

### OrionBelt (OBML) Converter

The OrionBelt converter handles the native OBML format. According to the source code in `converters/orionbelt/`, you can access this translator via:

```bash

# CLI usage

ossie-orionbelt obml-to-osi -i model.obml.yaml -o model.osi.yaml
ossie-orionbelt osi-to-obml -i model.osi.yaml -o model.obml.yaml

```

```python

# Python API

from ossie_orionbelt import OBMLtoOSI, OSItoOBML

```

### Snowflake YAML Converter

Located in [`converters/snowflake/src/osi_to_snowflake_yaml_converter.py`](https://github.com/apache/ossie/blob/main/converters/snowflake/src/osi_to_snowflake_yaml_converter.py), this module generates Snowflake-compatible semantic model YAML:

```bash
ossie-snowflake osi-to-snowflake -i model.osi.yaml -o model.snowflake.yaml
ossie-snowflake snowflake-to-osi -i model.snowflake.yaml -o model.osi.yaml

```

```python
from ossie_snowflake import OSIToSnowflakeYAML, SnowflakeYAMLToOSI

```

### GoodData JSON Converter

The GoodData converter, implemented in [`converters/gooddata/src/ossie_gooddata/osi_to_gooddata.py`](https://github.com/apache/ossie/blob/main/converters/gooddata/src/ossie_gooddata/osi_to_gooddata.py), manages JSON model exchanges:

```bash
ossie-gooddata osi-to-gooddata -i model.osi.yaml -o model.gooddata.json
ossie-gooddata gooddata-to-osi -i model.gooddata.json -o model.osi.yaml

```

```python
from ossie_gooddata import OSIToGoodData, GoodDataToOSI

```

### DBT MSI Converter

For dbt Metric Semantic Interface models, the 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) provides:

```bash
ossie-dbt osi-to-msi -i model.osi.yaml -o model.msi.yaml
ossie-dbt msi-to-osi -i model.msi.yaml -o model.osi.yaml

```

```python
from ossie_dbt import OSIToMSI, MSIToOSI

```

## Conversion Workflow and Architecture

Every converter follows a standardized four-step pipeline defined in the core implementation:

1. **Parse** – Ingests the source YAML/JSON into intermediate Python objects using parsers from [`python/src/ossie/models.py`](https://github.com/apache/ossie/blob/main/python/src/ossie/models.py)
2. **Map** – Translates OSI entities (datasets, fields, measures, dimensions, relationships) to the target schema
3. **Validate** – Checks against target JSON schemas using utilities from [`validation/validate.py`](https://github.com/apache/ossie/blob/main/validation/validate.py), with optional deep validation
4. **Emit** – Generates the target representation while preserving vendor-specific extensions in the OSI `custom_extensions` block

This architecture ensures that any format-to-OSI round-trip preserves original semantic information. The core data classes in [`python/src/ossie/models.py`](https://github.com/apache/ossie/blob/main/python/src/ossie/models.py) and validation utilities guarantee consistent behavior across all converters.

## CLI Commands for Model Translation

The CLI, implemented in [`cli/main.go`](https://github.com/apache/ossie/blob/main/cli/main.go) and [`cli/cmd/convert.go`](https://github.com/apache/ossie/blob/main/cli/cmd/convert.go), discovers sub-commands dynamically from installed converter packages. All commands accept common flags including `--no-validate`, `--output`, and `--input`.

Conversion warnings output to **stderr**, while a non-zero exit status indicates schema validation failures—critical for CI pipelines monitoring model compatibility.

**Example: Converting OBML to OSI**

```bash
ossie-orionbelt obml-to-osi \
    -i examples/flights.yaml \
    -o ./flights.osi.yaml

```

**Example: Snowflake round-trip conversion**

```bash

# Export to Snowflake format

ossie-snowflake osi-to-snowflake -i model.osi.yaml -o model.snowflake.yaml

# Import back to OSI

ossie-snowflake snowflake-to-osi -i model.snowflake.yaml -o model.osi.yaml

```

## Python API Implementation

For programmatic translation between Ossie and other semantic model formats, import the converter classes directly:

**Snowflake Conversion Example:**

```python
import yaml
from ossie_snowflake import OSIToSnowflakeYAML, SnowflakeYAMLToOSI, validate_osi

# Load an OSI model

with open("model.osi.yaml") as f:
    osi = yaml.safe_load(f)

# Convert OSI → Snowflake YAML

converter = OSIToSnowflakeYAML(osi)
snowflake_yaml = converter.convert()

# Validate the result

valid = validate_osi(snowflake_yaml)
assert valid.valid

# Convert back: Snowflake YAML → OSI

osi_back = SnowflakeYAMLToOSI(snowflake_yaml).convert()

```

## Preserving Vendor Extensions and Round-Trip Integrity

The OSI specification includes a **`custom_extensions`** field that carries format-specific payloads lacking native OSI counterparts. During reverse conversion, the system restores these extensions to their original locations, guaranteeing lossless round-trips.

**GoodData Round-Trip Example:**

```python
from ossie_gooddata import OSIToGoodData, GoodDataToOSI

# OSI → GoodData (vendor extensions preserved)

gd_json = OSIToGoodData(osi).convert()

# Round-trip back, extensions restored exactly

osi_round = GoodDataToOSI(gd_json).convert()
assert osi_round["custom_extensions"]["GOODDATA"] == osi["custom_extensions"]["GOODDATA"]

```

The converters support **OSI v0.2.0.dev0** as the default output format, while also accepting legacy OSI v0.1.x inputs through a normalization shim. Each converter ships with comprehensive test suites (e.g., `converters/orionbelt/tests/`, `converters/snowflake/tests/`) validating conversions against real-world models like the TPC-DS baseline found in [`examples/tpcds_semantic_model.yaml`](https://github.com/apache/ossie/blob/main/examples/tpcds_semantic_model.yaml).

## Summary

- The **`converters/`** directory contains bidirectional translators for OBML, Snowflake YAML, GoodData JSON, and DBT MSI formats
- Each converter provides both **CLI commands** (e.g., `ossie-snowflake`) and **Python APIs** (e.g., `OSIToSnowflakeYAML`)
- The conversion pipeline parses, maps, validates, and emits models while preserving **vendor extensions** in the `custom_extensions` block
- Core functionality relies on [`python/src/ossie/models.py`](https://github.com/apache/ossie/blob/main/python/src/ossie/models.py) for data classes and [`validation/validate.py`](https://github.com/apache/ossie/blob/main/validation/validate.py) for schema validation
- Round-trip conversions guarantee lossless translation, ensuring semantic integrity across different modeling platforms

## Frequently Asked Questions

### How do I convert a Snowflake semantic model to Ossie format?

Use the Snowflake converter CLI command `ossie-snowflake snowflake-to-osi -i model.snowflake.yaml -o model.osi.yaml` or import `SnowflakeYAMLToOSI` from the `ossie_snowflake` Python package. The converter maps Snowflake-specific entities to the canonical OSI representation while preserving any Snowflake-specific extensions in the `custom_extensions` field.

### What is the OSI core-spec and why is it important for translations?

The **OSI core-spec** is the canonical intermediate representation defined in [`python/src/ossie/models.py`](https://github.com/apache/ossie/blob/main/python/src/ossie/models.py) that serves as the "lingua franca" for all conversions. All translators convert source formats to this canonical form first, then map to the target format. This ensures that converting from Format A to Format B maintains semantic integrity even if no direct A→B converter exists.

### Can I preserve vendor-specific metadata when translating between formats?

Yes. The OSI model includes a **`custom_extensions`** field that stores vendor-specific payloads (e.g., GoodData-specific attributes or Snowflake-specific configurations) during conversion. When you convert OSI back to the original format, these extensions restore to their original locations, enabling lossless round-trips as demonstrated in the `ossie_gooddata` converter tests.

### Which CLI commands are available for model conversion?

The dynamic CLI in [`cli/main.go`](https://github.com/apache/ossie/blob/main/cli/main.go) provides format-specific commands: `ossie-orionbelt` for OBML, `ossie-snowflake` for Snowflake YAML, `ossie-gooddata` for GoodData JSON, and `ossie-dbt` for dbt MSI models. All commands support `--input`, `--output`, and `--no-validate` flags, output warnings to stderr, and return non-zero exit codes on validation failures for CI/CD integration.