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

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:

# 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 API

from ossie_orionbelt import OBMLtoOSI, OSItoOBML

Snowflake YAML Converter

Located in converters/snowflake/src/osi_to_snowflake_yaml_converter.py, this module generates Snowflake-compatible semantic model YAML:

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

from ossie_snowflake import OSIToSnowflakeYAML, SnowflakeYAMLToOSI

GoodData JSON Converter

The GoodData converter, implemented in converters/gooddata/src/ossie_gooddata/osi_to_gooddata.py, manages JSON model exchanges:

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

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

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

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
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, 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 and validation utilities guarantee consistent behavior across all converters.

CLI Commands for Model Translation

The CLI, implemented in cli/main.go and 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

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

Example: Snowflake round-trip conversion

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

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:

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.

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 for data classes and 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 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 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.

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