# Where to Find Reference Implementations for Ossie Converters in Apache Ossie

> Find Ossie converters reference implementations in the converters/ directory of the Apache Ossie repository. Explore vendor subfolders for translation logic between OSI and vendor formats.

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

---

**The reference implementations for Ossie converters are located in the `converters/` directory of the Apache Ossie repository, with each vendor maintaining a dedicated subfolder containing the bi-directional translation logic between the Ossie Semantic Interface (OSI) and vendor-specific formats.**

The Apache Ossie project provides canonical converter implementations that translate between the **Ossie Semantic Interface (OSI)** and various vendor-specific modeling languages. These reference implementations for Ossie converters follow a hub-and-spoke architecture centered in the `converters/` directory, enabling consistent bi-directional mapping between OSI and formats like OrionBelt Markup Language (OBML), Snowflake YAML, and dbt models.

## Directory Structure and Architecture

The `converters/` directory serves as the root for all translation logic in the apache/ossie repository. Each supported vendor maintains an isolated subfolder containing Python modules that handle the bi-directional transformation between OSI and the vendor's native format.

The architecture follows a **facade pattern** where `ossie_orionbelt.converter` acts as the main entry point, re-exporting concrete converter classes from sibling modules. This design ensures that existing imports (such as `ossie_orionbelt.converter.OSItoOBML`) remain stable while allowing vendor-specific implementations to evolve independently.

## Core Converter Components

### The Main Facade

The primary interface for all converters resides in [`converters/orionbelt/src/ossie_orionbelt/converter.py`](https://github.com/apache/ossie/blob/main/converters/orionbelt/src/ossie_orionbelt/converter.py). This module functions as a **public façade**, re-exporting symbols from concrete implementation files to maintain backward compatibility for downstream consumers.

Rather than importing directly from vendor-specific submodules, applications should import from this façade:

```python
from ossie_orionbelt.converter import OSItoOBML, OBMLtoOSI

```

### Export Converters (OSI → Vendor)

Export converters transform OSI representations into vendor-specific formats. Each vendor implements this logic in dedicated modules:

- **OrionBelt**: [`converters/orionbelt/src/ossie_orionbelt/osi_to_obml.py`](https://github.com/apache/ossie/blob/main/converters/orionbelt/src/ossie_orionbelt/osi_to_obml.py) contains the `OSItoOBML` class
- **Snowflake**: [`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) implements `osi_to_snowflake_yaml_converter`
- **dbt**: [`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 the `osi_to_msi` functionality
- **Omni**: [`converters/omni/src/osi_omni/osi_to_omni.py`](https://github.com/apache/ossie/blob/main/converters/omni/src/osi_omni/osi_to_omni.py) handles OSI-to-Omni translation
- **GoodData**: [`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) contains the `osi_to_gooddata` implementation
- **Honeydew**: [`converters/honeydew/src/honeydew_osi_converter.py`](https://github.com/apache/ossie/blob/main/converters/honeydew/src/honeydew_osi_converter.py) provides the `honeydew_osi_converter` class

### Import Converters (Vendor → OSI)

Import converters perform the reverse translation, ingesting vendor formats and producing canonical OSI models:

- **OrionBelt**: [`converters/orionbelt/src/ossie_orionbelt/obml_to_osi.py`](https://github.com/apache/ossie/blob/main/converters/orionbelt/src/ossie_orionbelt/obml_to_osi.py) implements the `OBMLtoOSI` class
- **dbt**: `msi_to_osi` handles dbt model imports (located alongside export logic)
- **Omni**: `omni_to_osi` provides bi-directional support
- **GoodData**: `gooddata_to_osi` enables GoodData-to-OSI translation

Note that **Snowflake** and **Honeydew** currently provide export-only implementations without corresponding import converters.

### Shared Utilities and Validation

All converters leverage common infrastructure located in the OrionBelt converter package:

- [`converters/orionbelt/src/ossie_orionbelt/_common.py`](https://github.com/apache/ossie/blob/main/converters/orionbelt/src/ossie_orionbelt/_common.py) houses **shared constants**, regex patterns, and vendor mapping tables used across all implementations
- [`converters/orionbelt/src/ossie_orionbelt/validation.py`](https://github.com/apache/ossie/blob/main/converters/orionbelt/src/ossie_orionbelt/validation.py) provides **JSON-Schema validation** for both OSI and OBML payloads, ensuring structural integrity before and after conversion

## Vendor-Specific Implementation Paths

The following breakdown maps each supported vendor to their specific implementation files within the `converters/` directory:

**OrionBelt (Reference Implementation)**
- Export: `OSItoOBML` class in [`converters/orionbelt/src/ossie_orionbelt/osi_to_obml.py`](https://github.com/apache/ossie/blob/main/converters/orionbelt/src/ossie_orionbelt/osi_to_obml.py)
- Import: `OBMLtoOSI` class in [`converters/orionbelt/src/ossie_orionbelt/obml_to_osi.py`](https://github.com/apache/ossie/blob/main/converters/orionbelt/src/ossie_orionbelt/obml_to_osi.py)
- Ontology: [`converters/orionbelt/src/ossie_orionbelt/ontology.py`](https://github.com/apache/ossie/blob/main/converters/orionbelt/src/ossie_orionbelt/ontology.py) manages OBML-to-OSI ontology mappings

**Snowflake**
- Export only: `osi_to_snowflake_yaml_converter` 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)

**dbt**
- Export: `osi_to_msi` 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)
- Import: `msi_to_osi` (bi-directional support)

**Omni**
- Export: `osi_to_omni` in [`converters/omni/src/osi_omni/osi_to_omni.py`](https://github.com/apache/ossie/blob/main/converters/omni/src/osi_omni/osi_to_omni.py)
- Import: `omni_to_osi` (bi-directional support)

**GoodData**
- Export: `osi_to_gooddata` 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)
- Import: `gooddata_to_osi` (bi-directional support)

**Honeydew**
- Export only: `honeydew_osi_converter` in [`converters/honeydew/src/honeydew_osi_converter.py`](https://github.com/apache/ossie/blob/main/converters/honeydew/src/honeydew_osi_converter.py)

## Working with Reference Implementations

### Command-Line Usage

The OrionBelt converter supports direct execution via Python's module interface:

```bash
python -m ossie_orionbelt.converter osi2obml model.yaml -o obml.yaml

```

This command executes the OSI-to-OBML conversion and writes the resulting OrionBelt markup to [`obml.yaml`](https://github.com/apache/ossie/blob/main/obml.yaml).

### Python API Integration

Import and instantiate converters directly for programmatic access:

```python
from ossie_orionbelt.converter import OSItoOBML, OBMLtoOSI
import yaml

# OSI → OBML conversion

with open("model.yaml") as f:
    osi_data = yaml.safe_load(f)
converter = OSItoOBML(osi_data, database="ANALYTICS", schema="PUBLIC")
obml = converter.convert()

# OBML → OSI conversion

converter = OBMLtoOSI(obml, name="my_model", description="Demo model")
osi = converter.convert()

```

### Extending the Converter Framework

To add a new vendor implementation, create a Python class following the established converter interface:

```python

# converters/myvendor/src/myvendor_converter.py

class OSItoMyVendor:
    def __init__(self, osi, **opts):
        self.osi = osi
        self.opts = opts
        self.warnings = []

    def convert(self):
        # Map OSI constructs to MyVendor format

        return my_vendor_representation

```

Expose the class via [`converters/myvendor/src/__init__.py`](https://github.com/apache/ossie/blob/main/converters/myvendor/src/__init__.py) and add corresponding test suites under `converters/myvendor/tests/`. Follow the validation patterns in [`converters/orionbelt/src/ossie_orionbelt/validation.py`](https://github.com/apache/ossie/blob/main/converters/orionbelt/src/ossie_orionbelt/validation.py) to ensure schema compliance.

## Summary

- The **reference implementations for Ossie converters** reside in the `converters/` directory at the root of the apache/ossie repository
- **OrionBelt** provides the canonical implementation and shared infrastructure, including validation utilities in [`converters/orionbelt/src/ossie_orionbelt/validation.py`](https://github.com/apache/ossie/blob/main/converters/orionbelt/src/ossie_orionbelt/validation.py)
- Each vendor maintains isolated subfolders (e.g., `converters/snowflake/`, `converters/dbt/`) containing specific export and import logic
- The **facade module** at [`converters/orionbelt/src/ossie_orionbelt/converter.py`](https://github.com/apache/ossie/blob/main/converters/orionbelt/src/ossie_orionbelt/converter.py) serves as the stable public API for all converter operations
- **Bi-directional support** varies by vendor: OrionBelt, dbt, Omni, and GoodData support full round-trip conversion, while Snowflake and Honeydew currently offer export-only capabilities

## Frequently Asked Questions

### Where exactly are the Ossie converter reference implementations located?

The reference implementations are located in the `converters/` directory within the apache/ossie GitHub repository. Each vendor has a dedicated subfolder (such as `converters/orionbelt/`, `converters/snowflake/`, or `converters/dbt/`) containing the Python source files that handle translation between OSI and vendor-specific formats.

### What is the main entry point for accessing OrionBelt converters?

The primary entry point is [`converters/orionbelt/src/ossie_orionbelt/converter.py`](https://github.com/apache/ossie/blob/main/converters/orionbelt/src/ossie_orionbelt/converter.py), which functions as a façade that re-exports concrete converter classes like `OSItoOBML` and `OBMLtoOSI`. This module ensures backward compatibility while abstracting the underlying implementation details found in [`osi_to_obml.py`](https://github.com/apache/ossie/blob/main/osi_to_obml.py) and [`obml_to_osi.py`](https://github.com/apache/ossie/blob/main/obml_to_osi.py).

### How does Apache Ossie handle validation in the converter pipeline?

Validation logic resides in [`converters/orionbelt/src/ossie_orionbelt/validation.py`](https://github.com/apache/ossie/blob/main/converters/orionbelt/src/ossie_orionbelt/validation.py), which provides JSON-Schema validation for both OSI and OBML payloads. This ensures that all data passing through the converters conforms to the expected semantic structure before and after transformation, preventing malformed models from propagating through the pipeline.

### Which vendors support bi-directional conversion in the Ossie converter framework?

OrionBelt, dbt, Omni, and GoodData support **bi-directional conversion**, providing both export (OSI → Vendor) and import (Vendor → OSI) capabilities. Snowflake and Honeydew currently provide **export-only** implementations, allowing OSI models to be converted to their formats but not vice versa.