OSI Interoperability

OSI (Open Semantic Interchange) is an open standard for portable semantic models, founded with the goal of letting metric and dimension definitions move between BI tools, semantic layers, and data platforms without rewriting. See open-semantic-interchange.org for the specification and contributor list.

Now at the Apache Incubator

OSI has been contributed to the Apache Software Foundation and is now developed as Apache Ossie (incubating). The specification and its converters (including the OrionBelt converter) live there going forward. Existing github.com/open-semantic-interchange/OSI links redirect to the new repository.

OrionBelt includes a bidirectional converter between OBML and the OSI specification format. The converter handles structural differences between the two formats — including metric decomposition, relationship restructuring, and lossless ai_context preservation via customExtensions — with built-in validation for both directions.

The converter ships as a standalone osi-orionbelt package. It is an optional dependency: install it with pip install 'orionbelt-semantic-layer[osi]' (or standalone via pip install osi-orionbelt). The published API Docker images bundle it, so the /convert, /models/from-osi, and /osi endpoints work out of the box; on a bare install without the extra, those endpoints return a 503.

Spec version

OBSL v2.6 emits OSI v0.2.0.dev0 (the latest draft in the upstream core-spec/ at release time). The vendored schema lives at packages/osi-orionbelt/src/osi_orionbelt/schemas/osi-schema.json; refresh it with scripts/refresh-osi-schema.sh when upstream advances.

Breaking change vs. OBSL v2.5 — the previous release emitted OSI v0.1.1. Downstream consumers pinning to v0.1 will reject v2.6 output. The converter still reads v0.1.x inputs via the legacy shim _normalize_legacy_v01(), which promotes pre-v0.2 custom_extensions payloads (obml_primary_key, obml_unique_keys) into the v0.2 first-class fields before parsing.

What's new in v0.2 that OBSL now round-trips:

Surface	OBML side	OSI side
primary_key	Per-column primaryKey: true flag	First-class primary_key: [col, ...] array (composite supported, declaration order preserved)
unique_keys	OBSL custom extension obml_unique_keys: [[col], [col1, col2], ...]	First-class unique_keys: [[...], ...] array
Field label	OBSL custom extension obml_field_label	First-class field.label string
MAQL dialect	n/a (we don't generate MAQL)	Accepted on read, surfaced via warning if it's the only available dialect
Top-level informational arrays	n/a	dialects: ["ANSI_SQL"] + vendors: [...]

REST API

# Convert OSI -> OBML
curl -X POST http://127.0.0.1:8000/v1/convert/osi-to-obml \
  -H "Content-Type: application/json" \
  -d '{"input_yaml": "version: \"0.1.1\"\nsemantic_model:\n  ..."}' | jq

# Convert OBML -> OSI
curl -X POST http://127.0.0.1:8000/v1/convert/obml-to-osi \
  -H "Content-Type: application/json" \
  -d '{"input_yaml": "version: 1.0\ndataObjects:\n  ..."}' | jq

Both endpoints are stateless — no session required.

The converter targets the OSI core-spec semantic model (datasets, fields, relationships, metrics) in both directions. OSI's separate ontology layer is out of scope.

Gradio UI

The Gradio UI provides Import OSI / Export to OSI buttons that use these API endpoints, with validation feedback for both directions.

Mapping Reference

See the OSI - OBML Mapping Analysis for the core-spec mapping.