Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 23 additions & 19 deletions converters/honeydew/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,20 +17,24 @@
under the License.
-->

# OSI ↔ Honeydew Converter
# Apache Ossie ↔ Honeydew Converter

Bidirectional converter between [OSI](../../core-spec/spec.md) semantic models and [Honeydew](https://honeydew.ai/docs) workspace YAML.
Bidirectional converter between [Apache Ossie](../../core-spec/spec.md) semantic models
and [Honeydew](https://honeydew.ai/docs) [workspace YAML](https://honeydew.ai/docs/yaml-schema).

Honeydew documents this integration from its own side under
[Apache Ossie (OSI)](https://honeydew.ai/docs/integration/apache-ossie-osi).

## Overview

| Direction | Input | Output |
|-----------|-------|--------|
| `osi-to-honeydew` | Single OSI YAML file | Honeydew workspace directory |
| `honeydew-to-osi` | Honeydew workspace directory | Single OSI YAML file |
| `ossie-to-honeydew` | Single Ossie YAML file | Honeydew workspace directory |
| `honeydew-to-ossie` | Honeydew workspace directory | Single Ossie YAML file |

### OSI → Honeydew mapping
### Ossie → Honeydew mapping

| OSI concept | Honeydew concept |
| Ossie concept | Honeydew concept |
|-------------|-----------------|
| `semantic_model.name` | `workspace.yml name` |
| `dataset` | Entity + dataset files under `schema/<entity>/` |
Expand All @@ -42,9 +46,9 @@ Bidirectional converter between [OSI](../../core-spec/spec.md) semantic models a
| `relationship` (from → to) | `entity.relations` on the "from" entity (`rel_type: many-to-one`) |
| `metric` | `metric` YAML (assigned to entity by expression parse) |

### Honeydew → OSI mapping
### Honeydew → Ossie mapping

| Honeydew concept | OSI concept |
| Honeydew concept | Ossie concept |
|-----------------|-------------|
| `workspace.name` | `semantic_model.name` |
| Entity + primary dataset | `dataset` |
Expand All @@ -69,11 +73,11 @@ uv sync
## Usage

```bash
# OSI YAML → Honeydew workspace directory
uv run honeydew-osi osi-to-honeydew -i input.yaml -o output_dir/
# Ossie YAML → Honeydew workspace directory
uv run ossie-honeydew ossie-to-honeydew -i input.yaml -o output_dir/

# Honeydew workspace directory → OSI YAML
uv run honeydew-osi honeydew-to-osi -i workspace_dir/ -o output.yaml
# Honeydew workspace directory → Ossie YAML
uv run ossie-honeydew honeydew-to-ossie -i workspace_dir/ -o output.yaml
```

## Tests
Expand All @@ -84,10 +88,10 @@ uv run pytest

## Limitations

- **One source dataset per entity**: Honeydew entities can have multiple source dataset files; the converter always generates exactly one, because an OSI `dataset` block describes a single table or SQL query.
- **Datatype inference**: OSI fields have no explicit datatype; the converter infers Honeydew datatypes from the `dimension.is_time` flag (`timestamp`) and the presence/absence of the `dimension` key (`string` vs `number`).
- **Honeydew SQL expressions**: Calculated attributes and metrics use Honeydew's `entity.attribute` reference syntax. These are exported as `ANSI_SQL` dialect expressions in OSI; they remain valid for round-tripping but may not run on other databases without adaptation.
- **Perspectives and domains**: Not converted (no OSI equivalent).
- **Connection expressions** (`connection_expr`): Preserved in `HONEYDEW` custom extensions on the OSI relationship and restored on the return trip.
- **`ai_context`**: OSI `ai_context` fields (synonyms, instructions) are stored in Honeydew `metadata` for round-trip recovery. Instructions are also merged into `description` for human readability.
- **`unique_keys`**: A Honeydew entity's `keys` uniquely identify its rows — Honeydew enforces this and validates that relations join to those keys — so they are emitted as the OSI dataset's `primary_key` *and* a `unique_keys` entry. This surfaces the join-target cardinality for OSI consumers (e.g. a many-to-one relation's `to_columns` are always covered by the target's `unique_keys`). A unique key identical to the primary key is not stored back in Honeydew `metadata` on the return trip, so `Honeydew → OSI → Honeydew` stays clean; `OSI → Honeydew → OSI` normalizes by surfacing the primary key as a unique key.
- **One source dataset per entity**: Honeydew entities can have multiple source dataset files; the converter always generates exactly one, because an Ossie `dataset` block describes a single table or SQL query.
- **Datatype inference**: Ossie fields have no explicit datatype; the converter infers Honeydew datatypes from the `dimension.is_time` flag (`timestamp`) and the presence/absence of the `dimension` key (`string` vs `number`).
- **Honeydew SQL expressions**: Calculated attributes and metrics use Honeydew's `entity.attribute` reference syntax. These are exported as `ANSI_SQL` dialect expressions in Ossie; they remain valid for round-tripping but may not run on other databases without adaptation.
- **Perspectives and domains**: Not converted (no Ossie equivalent).
- **Connection expressions** (`connection_expr`): Preserved in `HONEYDEW` custom extensions on the Ossie relationship and restored on the return trip.
- **`ai_context`**: Ossie `ai_context` fields (synonyms, instructions) are stored in Honeydew `metadata` for round-trip recovery. Instructions are also merged into `description` for human readability.
- **`unique_keys`**: A Honeydew entity's `keys` uniquely identify its rows — Honeydew enforces this and validates that relations join to those keys — so they are emitted as the Ossie dataset's `primary_key` *and* a `unique_keys` entry. This surfaces the join-target cardinality for Ossie consumers (e.g. a many-to-one relation's `to_columns` are always covered by the target's `unique_keys`). A unique key identical to the primary key is not stored back in Honeydew `metadata` on the return trip, so `Honeydew → Ossie → Honeydew` stays clean; `Ossie → Honeydew → Ossie` normalizes by surfacing the primary key as a unique key.
8 changes: 4 additions & 4 deletions converters/honeydew/pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -26,9 +26,9 @@ dev = [
]

[project]
name = "honeydew-osi"
name = "apache-ossie-honeydew"
version = "0.2.0.dev0"
description = "Bidirectional converter between Honeydew workspace YAML and OSI semantic model"
description = "Honeydew workspace YAML <> Apache Ossie converter"
authors = [{ name = "Apache Software Foundation", email = "dev@ossie.apache.org" }]
requires-python = ">=3.12"
readme = "README.md"
Expand All @@ -43,14 +43,14 @@ dependencies = [
]

[project.scripts]
honeydew-osi = "honeydew_osi.converter:main"
ossie-honeydew = "ossie_honeydew.converter:main"

[project.urls]
homepage = "https://ossie.apache.org/"
repository = "https://github.com/apache/ossie/"

[tool.hatch.build.targets.wheel]
packages = ["src/honeydew_osi"]
packages = ["src/ossie_honeydew"]

[tool.pytest.ini_options]
testpaths = ["tests"]
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -13,4 +13,4 @@
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
# KIND, either express or implied. See the License for the
# specific language governing permissions and limitations
# under the License.
# under the License.
Loading