Apache Ossie: a vendor-neutral spec for semantic model exchange

The fragmentation problem Apache Ossie targets

Every analytics stack accumulates definitions. A revenue metric lives in the BI tool, a slightly different one lives in the transformation layer, and a third version lives in whatever the AI agent was told during its last prompt revision. The README states the project addresses exactly this: "the same KPI defined differently across tools, teams spending significant effort manually reconciling definitions, and AI agents producing unreliable outputs grounded in inconsistent business logic." That third item is the newer motivation. Retrieval and agent tooling have made semantic definitions load-bearing for systems that never had a formal contract for them before.

The intended audience is not a single analyst. It is whoever owns the interchange format between platforms: semantic layer engineers, BI platform vendors, and the teams wiring AI agents to governed metrics. Ossie was formerly known as Open Semantic Interchange (OSI), so older references and discussion threads may use that name. The project is in the Apache incubator, which means the specification and its governance are still being established rather than settled.

What the repository actually contains

The layout is the clearest statement of scope. core-spec/ holds spec.md, the machine-readable spec.yaml, and ossie-schema.json. converters/ holds reference converters that translate between Ossie and other semantic formats, with dbt, GoodData, Polaris and Salesforce named in the README. examples/ holds sample semantic models including a complete TPC-DS model. validation/ holds tooling for checking a model against the Ossie schema. docs/ holds project documentation.

Two directories are not described in the README body: ontology/ and bi-sql-examples/, both of which appear in the top-level listing. The README does not explain what either contains, so anyone evaluating dialect coverage should open them directly rather than assume. The same applies to cli/ and compliance/, which are present at the top level but absent from the "What's in this repository" list. The README is a good index of the specification and converters and a poor index of everything else.

How the interchange format works

Ossie is a data format, not a service. The README describes it as "a single JSON- and YAML-based specification that any tool can read and write." A semantic model is serialized into that format, and each participating tool implements a reader, a writer, or both. There is no central registry and no runtime broker in the described design: the file is the interface.

That choice has consequences worth stating plainly. A file-based contract is easy to version and easy to review in a pull request, which suits specification work. It also means consistency depends entirely on each tool's converter being correct. If a BI platform writes a metric with a subtly different aggregation than the source model intended, Ossie will faithfully carry the discrepancy across. The schema can constrain structure; it cannot verify that a translated definition means the same thing. The validation/ directory addresses conformance to the schema, and the README does not claim it addresses semantic equivalence. That gap is the honest boundary of what the project can enforce.

A first real use: reading an example and validating against the schema

The README does not give install commands. It points contributors to CONTRIBUTING.md and lists the repository directories, so the practical entry point is the repository itself. Clone it, then work from the examples and validation directories.

git clone https://github.com/apache/ossie.git

The examples directory contains ready-made models, including examples/flights.yaml and examples/tpcds_semantic_model.yaml. Read one before writing your own, because the shape of a valid model is defined by core-spec/spec.yaml and ossie-schema.json rather than by prose alone. The README does not document a copy or scaffolding command, so start from an existing example file and edit the fields.

Validation is the part of the workflow the repository explicitly provides tooling for. The README describes validation/ as "Tooling for validating semantic models against the Ossie schema," so the check to run is whatever entry point that directory exposes against ossie-schema.json. Expect a pass or a schema violation; the README does not document error codes, so treat the schema file as the reference when a field is rejected. If your model originates in dbt, GoodData, Polaris or Salesforce, check converters/ before writing anything by hand, since a reference converter may already cover the direction you need.

Where Ossie is the wrong tool

Ossie does not execute queries. Nothing in the README describes a query engine, a cache, or a metrics API. If you need a semantic layer that answers requests at runtime, Ossie is the wrong layer of the stack: it defines how definitions travel, not how they are served. Teams sometimes read "semantic layer" and expect a serving component. There is none here.

Governance is the second limit. A specification can standardize the shape of a metric definition, but adoption depends on vendors implementing it. The converters in this repository are reference implementations, and the README does not claim they are exhaustive or that any commercial platform ships native support. Before planning a migration, confirm that the specific tools on both ends of your pipeline can read or write the format. The README also does not document rollback, deprecation handling, or a compatibility policy between schema revisions, which matters if you are pinning a version in a production pipeline.

How Ossie differs from a metrics API layer

The closest comparison is a metrics API such as Cube or MetricFlow, where the tool both stores definitions and serves queries against them. Those systems give you a running endpoint and a query planner; their format is internal to their own runtime. Ossie inverts that. It standardizes the artifact and leaves execution to whoever consumes it, which is why the repository is mostly specification, schema and converters rather than a server.

The trade-off is direct. With a metrics API you get one coherent system and accept lock-in to its definition model. With Ossie you get a portable artifact and accept that portability is only as good as the converters on each side. For a single-vendor stack, the API layer is less work. For an organization that already runs three BI tools and an agent framework, the interchange format addresses a problem the API layer cannot, because it does not require every consumer to be the same product.

Licence, contribution and upgrade cost

The project is licensed under Apache-2.0, with the LICENSE and NOTICE files at the repository root and the ASF header reproduced at the top of the README. For most adopters this is a permissive licence with no copyleft obligation on the specification text or the reference converters; the NOTICE file carries attribution requirements, and anyone redistributing a modified copy should read it rather than rely on a summary. This is not legal advice.

The upgrade cost is the part the README does not address. There are no retrieved releases, and the README does not describe a versioning scheme for the specification, so a team pinning ossie-schema.json has no documented statement about how breaking changes will be signalled. Contribution is governed by CONTRIBUTING.md, and ROADMAP.md lists working groups and planned enhancements. Both are worth reading before you build a pipeline on a specific schema revision, because they are the only place the project states where the format is heading.

Editorial conclusion

Adopt Ossie if you maintain a semantic layer and need to move definitions between tools without hand-reconciliation, and start by reading core-spec/spec.md and validating an existing model against ossie-schema.json. Do not adopt it expecting a production runtime: the repository offers a specification, converters and validation tooling, not a query engine. Before committing, verify which converters cover your source format, check whether your dialect appears under bi-sql-examples/, and confirm the schema version you target exists in core-spec/, because the README does not document a versioning or migration policy.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository