# What Is Apache Ossie? How Does It Works? > Learn what Apache Ossie is, how its semantic model works, and how it enables interoperability across BI, analytics, AI agents, and data platforms. - Canonical URL: https://www.puppygraph.com/blog/apache-ossie - Published: 2026-09-24 - Author: Hao Wu A shared data warehouse does not guarantee a shared definition of revenue, customer, or active account. Two applications can read the same tables and answer the same business question differently because they apply different filters, join paths, or aggregation rules. Apache Ossie addresses the exchange of those definitions, making semantic models available in a common format that participating tools can interpret. This article explains what Ossie represents, how its model works, and where interoperability still depends on the consuming platform. It also walks through a small model and shows how an AI assistant can generate a graph schema from connected tables, which can then be exported as reusable Ossie metadata. [Get Started with PuppyGraph for FREE](https://www.puppygraph.com/download-confirmation) ## What is Apache Ossie? [Apache Ossie (incubating)](https://ossie.apache.org/) is an open specification for exchanging semantic metadata across analytics, business intelligence, and AI systems. Previously known as Open Semantic Interchange, it provides a common representation for definitions that would otherwise be stored in tool-specific formats. A semantic model connects physical data to the concepts people use when asking questions. A table might contain `customer_id`, `status`, and `amount`; the model explains which dataset represents orders, how orders relate to customers, and which calculation represents a business metric. Ossie's contribution is making that description exchangeable. The distinction between a model and the software using it is central: | Component | Responsibility in an Analytics System | | --- | --- | | Source Tables | Hold the records being analyzed. | | Semantic Model | Describe the relevant datasets, relationships, fields, and calculations. | | Ossie Document | Encode supported semantic definitions in an interchange format. | | Consuming Platform | Interpret the model, apply supported behavior, and arrange query execution. | The [project repository](https://github.com/apache/ossie) contains the specification, schemas, examples, validation tools, and converters. Adopting these artifacts does not itself deploy a database or a query service. A BI platform still needs an integration that can read the model, and a query engine still needs access to the underlying data. That separation makes the adoption question concrete: which definitions can a producer export, and which can the intended consumer preserve and use? [Get Started with PuppyGraph for FREE](https://www.puppygraph.com/download-confirmation) ## What does Apache Ossie stand for? Ossie is the project's new name. Its predecessor, **OSI**, stands for **Open Semantic Interchange**. The [project's July 2026 naming announcement](https://ossie.apache.org/updates/ossie-enters-apache-incubator/) explains that the community chose Ossie to avoid confusion with other projects using the OSI acronym as it entered the Apache Incubator. The older name remains relevant when reading examples, repository history, and integrations developed before the rename. An OSI model and an Ossie model belong to the same project's lineage. Compatibility, however, depends on the specification version and document structure, not simply on which name appears in a filename. [Get Started with PuppyGraph for FREE](https://www.puppygraph.com/download-confirmation) ## Why was Apache Ossie created? Semantic definitions are useful beyond the application where they were first written. A finance dashboard, an analyst's notebook, and an AI assistant might all need the same definition of completed-order revenue. If each integration requires translating that definition into another format, the organization has several implementations to maintain whenever the business rule changes. Ossie's [incubation proposal](https://cwiki.apache.org/confluence/spaces/INCUBATOR/pages/430408796/OssieProposal) identifies this fragmentation as the problem behind the project. Its aim is a shared representation that lets independently developed tools exchange semantic metadata. Consider a company changing its revenue reporting to exclude test accounts. The business decision is straightforward. The engineering work becomes harder if that rule lives separately in a dashboard formula, a semantic-layer configuration, and instructions supplied to an AI application. Each copy needs updating, and each update needs checking against the others. A common exchange format gives these systems a way to share the approved definition. It also gives reviewers an artifact they can inspect outside a particular dashboard editor. The team still needs to decide who owns the rule and how changes reach consumers, but it has a common representation around which to build that process. The reason for standardization is therefore practical: maintaining meaning across application boundaries should require less repeated translation work. [Get Started with PuppyGraph for FREE](https://www.puppygraph.com/download-confirmation) ## What problem does Apache Ossie solve? Ossie targets semantic interoperability: moving descriptions of data and business logic between systems. The problem appears at several levels, even when every application has reliable access to the same records. **Metric definitions.** Imagine one dashboard including all orders while another counts only completed orders. Both might display a number labeled revenue. Exchanging a metric's expression and description makes that difference inspectable. The organization must still decide which definition belongs in which report. **Relationships and row grain.** Suppose an order worth $100 has three line items. Joining the order total to every line item and summing it produces $300. A useful model needs to expose the relevant relationships and keys so the consuming system can plan the calculation correctly. Recording a relationship does not, by itself, prove that every downstream aggregation handles this case. **Business vocabulary.** An AI assistant asked about customers needs more context than a collection of column names. It needs to distinguish purchasers from billing accounts, and completed purchases from abandoned checkouts. Shared descriptions give an integration explicit material to use when resolving those terms. These are different problems from data replication or storage compatibility. Copying another set of rows would not resolve the disagreement about what revenue means. Ossie supplies a format for expressing and exchanging the relevant definitions; its value depends on the definitions being correct and the receiving system using them faithfully. [Get Started with PuppyGraph for FREE](https://www.puppygraph.com/download-confirmation) ## How does Apache Ossie work? The workflow has three parts: represent a semantic model, exchange it, and interpret it in a consuming application. The [core specification](https://github.com/apache/ossie/blob/release/0.1.1/core-spec/spec.md) defines the main components: | Component | What It Records | Example | | --- | --- | --- | | Dataset | A logical dataset and its physical source | `orders` mapped to `sales.public.orders` | | Field | A row-level expression and descriptive metadata | An order date or customer identifier | | Relationship | Connections between datasets through key columns | Orders linked to customers | | Metric | An aggregate expression | Completed-order revenue | | AI Context | Optional instructions or contextual metadata | Terms an application can associate with a dataset | Field and metric expressions identify their dialect. A model can carry multiple dialect variants, while custom extensions provide room for vendor-specific metadata. These mechanisms let a producer describe supported semantics without assuming that every platform has identical capabilities. On the exchange side, the converter architecture uses Ossie as a shared intermediate format. A producer converts its native model into Ossie, and a consumer reads Ossie directly or converts it into another native representation. This reduces the need to build a separate translator for every pair of formats. For example, an integration might export the finance team's approved model, validate the resulting file, and import it into an analytics application. That application then resolves its source references, applies supported expressions, and executes queries through its own runtime. Data connections and execution remain part of that deployment. ![](https://o6xswp5m6ilbks2z.public.blob.vercel-storage.com/blog-94ac098bb972cb39fcbf8b2c6d92ee5ab1cac0c309abdc5c752cdc08c9668280.webp) Figure: Ossie carries semantic definitions between tools; each consuming platform still connects to the source data and executes its own queries. Validation belongs at the boundary between these stages. Ossie's [validator](https://github.com/apache/ossie/blob/main/validation/validate.py) checks document structure and additional conditions such as duplicate names and relationship references. Passing those checks gives an integration a stronger starting point. A business-level test must still establish that the imported model answers the intended question correctly. In practice, interoperability has two tests: whether the receiving tool can read the artifact, and whether it preserves the meaning that matters to the workload. [Get Started with PuppyGraph for FREE](https://www.puppygraph.com/download-confirmation) ## Benefits of Apache Ossie **Less repeated modeling.** When two applications can exchange the definitions they both support, a team can reuse an existing model instead of manually reconstructing it. For a small adoption project, the useful measure is how many definitions survive the transfer and how much manual repair remains. **More visible differences.** An exported artifact gives reviewers something concrete to compare. A change from all orders to completed orders can be reviewed alongside its expression and description. Teams can store these files in version control and associate model changes with expected changes in query results. **Reusable context for AI applications.** An integration can provide an assistant with approved names, descriptions, and relationships rather than asking it to infer every business concept from physical schema names. This creates a clearer basis for evaluating generated queries. It does not establish that an assistant will always choose the right metric or respect every instruction. **More options when adopting another tool.** A portable representation can preserve part of the modeling investment when adding a consumer or evaluating a replacement. The relevant question is how much of the existing model transfers accurately, including its less convenient cases. A clean demonstration with one sum is only a starting point. These benefits accumulate when an organization treats the exchanged model as a maintained artifact. Assigning ownership, reviewing changes, and testing consumer behavior turn file exchange into a dependable workflow. [Get Started with PuppyGraph for FREE](https://www.puppygraph.com/download-confirmation) ## Limitations and challenges of Apache Ossie **Conversion can lose information.** A common format cannot guarantee that every feature of every source model has an equivalent in every target. For example, the official dbt converter documentation lists conversion losses involving some metric types and cumulative semantics. Its warnings are part of the integration result and need review before accepting the exported file. **Expression portability needs testing.** Recognizing a dialect name is different from executing its expressions with equivalent behavior. For a real workload, test date boundaries, null values, distinct counts, and decimal calculations. A monthly revenue comparison can disagree because of time-zone treatment even when both tools import the model successfully. **A shared file does not settle business disagreement.** Two teams might intentionally use different customer definitions. Giving both definitions a common syntax will not merge them into a single concept. Name them clearly, document their scope, and decide which applications should consume each one. Likewise, publishing metadata does not configure the receiving platform's data permissions. **The specification is evolving.** As of September 22, 2026, the [development specification](https://github.com/apache/ossie/blob/main/core-spec/spec.md) identifies itself as a draft and documents a breaking change from a `semantic_model` wrapper to a single model at the document root. An example for one version cannot safely be treated as input for every implementation. The [community roadmap](https://github.com/apache/ossie/blob/main/ROADMAP.md) also includes work on richer metric semantics, catalog integration, and a standardized semantic query interface. Treat each capability according to its implemented and documented state. A roadmap describes intended work; an adoption decision needs evidence from the specific schema, converter, and consumer being evaluated. [Get Started with PuppyGraph for FREE](https://www.puppygraph.com/download-confirmation) ## Is Apache Ossie production ready? Production readiness needs to be assessed for a particular integration. Apache Ossie is an incubating project as of September 22, 2026. The project's [Apache disclaimer](https://github.com/apache/ossie/blob/main/DISCLAIMER) says incubation is not necessarily a reflection of code completeness or stability. It concerns the project's progress within Apache, so it is neither a production certification nor a blanket reason to reject an implementation. For an operational deployment, establish a narrower set of evidence: 1. **Version agreement:** the producer, schema validator, and consumer accept the same document version. 2. **Coverage:** every required definition survives conversion, with omissions reviewed explicitly. 3. **Behavior:** representative queries return the expected results on controlled data. 4. **Operations:** the team can deploy, monitor, and roll back a model change. Consider a weekly internal dashboard using a simple aggregate. Its acceptance tests may be relatively small. A customer-facing reporting API with cumulative metrics, historical attributes, and strict access rules needs a broader test set. Both could use Ossie, but their operational requirements differ substantially. A sensible first deployment is a bounded exchange path with a named owner and a tested set of semantics. Expand it when the actual consumers demonstrate the required behavior. The presence of an exporter or a project logo alone is insufficient evidence of complete compatibility. [Get Started with PuppyGraph for FREE](https://www.puppygraph.com/download-confirmation) ## How to get started with Apache Ossie Start with one business question and one consumer. For example: what is the total value of completed orders, using the currency already normalized in the source table? This keeps the first model small enough to inspect and gives you a result to test. **Choose the document version first.** The example below uses the `0.1.1` structure defined by the [versioned JSON Schema](https://github.com/apache/ossie/blob/release/0.1.1/core-spec/osi-schema.json). It is a hand-authored teaching example, and the source table must exist before a consuming platform can query it. Save it as `orders.ossie.yaml`: ```yaml version: "0.1.1" semantic_model: - name: order_reporting description: Completed-order reporting in a normalized currency. datasets: - name: orders source: sales.public.orders primary_key: [order_id] fields: - name: order_id expression: dialects: - dialect: ANSI_SQL expression: order_id - name: status expression: dialects: - dialect: ANSI_SQL expression: status - name: amount expression: dialects: - dialect: ANSI_SQL expression: amount metrics: - name: completed_order_revenue description: Sum of completed order amounts, before refunds. expression: dialects: - dialect: ANSI_SQL expression: >- SUM(CASE WHEN orders.status = 'completed' THEN orders.amount ELSE 0 END) ``` The metric's name, expression, and description should agree. Here, refunds are outside the definition. If finance requires revenue after refunds, change the model deliberately and add the corresponding data and tests. A table name cannot establish that policy for you. **Validate against the matching schema.** From a directory containing the YAML file, the following commands obtain the versioned schema and validate the document's structure in a local Python environment: ``` python -m venv .venv . .venv/bin/activate python -m pip install pyyaml jsonschema curl -fsSL \ https://raw.githubusercontent.com/apache/ossie/release/0.1.1/core-spec/osi-schema.json \ -o osi-schema.json python - <<'PY' import json from pathlib import Path import yaml from jsonschema import Draft202012Validator schema = json.loads(Path("osi-schema.json").read_text()) model = yaml.safe_load(Path("orders.ossie.yaml").read_text()) Draft202012Validator(schema).validate(model) print("Document structure is valid") PY ``` This command checks schema conformance. It does not connect to the database, evaluate the SQL expression, or confirm the definition with finance. Keep the schema revision alongside the model so subsequent checks use the same contract. **Exercise the consumer.** Import the document through an integration supporting this version. Configure its connection to the source and check a small fixture: completed orders worth 100 and 50, plus a cancelled order worth 80, should produce 150. Compare that result with a directly executed reference calculation. Then test empty inputs, null amounts, and any joins you add. Once the basic calculation agrees, extend the model one feature at a time. A customer relationship or reporting date adds more useful coverage than a large first export whose discrepancies are difficult to isolate. [Get Started with PuppyGraph for FREE](https://www.puppygraph.com/download-confirmation) ## Apache Ossie architecture example Consider a retailer with order and customer tables in its warehouse, a BI application for reporting, and an AI assistant for analyst questions. A practical architecture separates model ownership, metadata exchange, and query execution. The data team maintains the source mappings and approved metric definitions. A producer exports an Ossie document, validation checks it, and the approved artifact is distributed to the two consuming integrations. Each consumer maps supported definitions into its own runtime and connects to the warehouse with the appropriate access controls. For a question about completed-order revenue by customer region, the integration needs the order metric, the customer attribute, and the relationship joining them. Acceptance tests should confirm that the relationship does not multiply order totals. Model review should also establish whether region means the customer's current region or its value at the time of purchase. ![](https://o6xswp5m6ilbks2z.public.blob.vercel-storage.com/blog-c032abf9362e5986953349384ca8d440994932a913343f813f989387b1ae2d8a.webp) Figure: BI and AI consumers can reuse the same revenue definition and customer relationship while executing through their own runtimes. [PuppyGraph](https://www.puppygraph.com/) can help create the model starting from connected tables. Its built-in AI assistant acts as a modeling agent: it inspects catalog metadata, samples rows, profiles columns, and tests candidate joins to propose a graph schema. Once you review and apply that schema, PuppyGraph's Ossie exporter turns the supported table and relationship mappings into an Apache Ossie document. This connects two stages of automation: generating the graph schema and generating the interchange file from it. This walkthrough follows the retail example in the demonstration video below. It starts with a PostgreSQL catalog named `shop` already connected and an empty graph schema. The retail schema contains five source tables: `customers`, `orders`, `order_items`, `products`, and `reviews`. The assistant builds a graph from those tables, and PuppyGraph exports the resulting mappings as an Apache Ossie document. #### **Generate the graph schema** On the **Graph** page, click **Auto Graph Builder** to open PuppyGraph AI. Turn **Auto-confirm** on to match the video, allowing the assistant to apply its schema changes automatically. Enter the following prompt: ``` Build a graph schema for me from my connected catalogs. Use the retail tables in the shop catalog. Make every table a node, and point each edge from the table that holds the foreign key to the table it references. ``` ![The prompt asks PuppyGraph AI to model the retail tables as nodes and follow foreign-key references when creating edges.](https://o6xswp5m6ilbks2z.public.blob.vercel-storage.com/blog-676fea8cd98b824c8af260fc7090283c659052f4c591950c740a42671f59dd62.webp) Figure: The prompt asks PuppyGraph AI to model the retail tables as nodes and follow foreign-key references when creating edges. #### **Review the generated mappings** The assistant inspects the retail tables and their foreign-key relationships, then applies five node types. The run shown in the video produces the following mappings and counts: | Source Table | Node Label | Node ID | Count | | --- | --- | --- | --- | | `customers` | `Customer` | `customer_id` | 5 | | `orders` | `Order` | `order_id` | 6 | | `order_items` | `OrderItem` | `(order_id, product_id)` | 9 | | `products` | `Product` | `product_id` | 5 | | `reviews` | `Review` | `review_id` | 5 | `OrderItem` uses `(order_id, product_id)` as its composite ID. The five edge types point from the table holding each foreign key to the table it references: ``` Order -[:PLACED_BY]-> Customer OrderItem -[:PART_OF]-> Order OrderItem -[:REFERS_TO]-> Product Review -[:WRITTEN_BY]-> Customer Review -[:REVIEWS]-> Product ``` ![The assistant reports five node types and five edge types, with OrderItem identified by the combination of order\_id and product\_id.](https://o6xswp5m6ilbks2z.public.blob.vercel-storage.com/blog-33340347ca93e2450d4a250fa4b0e359511a78286899c6621962c3d5e600a66e.webp) Figure: The assistant reports five node types and five edge types, with `OrderItem` identified by the combination of `order_id` and `product_id`. #### **Verify the edge counts** The assistant also checks that the applied edge mappings return data. To reproduce the edge-count check shown in the video, run: ``` MATCH (:Order)-[e1:PLACED_BY]->(:Customer) WITH count(e1) AS placed_by MATCH (:OrderItem)-[e2:PART_OF]->(:Order) WITH placed_by, count(e2) AS part_of MATCH (:OrderItem)-[e3:REFERS_TO]->(:Product) WITH placed_by, part_of, count(e3) AS refers_to MATCH (:Review)-[e4:WRITTEN_BY]->(:Customer) WITH placed_by, part_of, refers_to, count(e4) AS written_by MATCH (:Review)-[e5:REVIEWS]->(:Product) RETURN placed_by, part_of, refers_to, written_by, count(e5) AS reviews ``` Each `WITH` carries forward the preceding count while the next `MATCH` counts another edge type. For the sample data shown in the video, the result is: | `placed_by` | `part_of` | `refers_to` | `written_by` | `reviews` | | --- | --- | --- | --- | --- | | 6 | 9 | 9 | 5 | 5 | ![The assistant verifies the five edge types and returns counts of 6, 9, 9, 5, and 5.](https://o6xswp5m6ilbks2z.public.blob.vercel-storage.com/blog-ba5dba6656e321b3415c43bcae15a0a67e2c4f1cf9b5111c51d9c6f04157fb89.webp) Figure: The assistant verifies the five edge types and returns counts of 6, 9, 9, 5, and 5. #### **Export the Ossie model** Open **Graph**, click **Download**, and select **Download Apache Ossie Model (YAML)**. The video downloads `schema.ossie.yaml` and then demonstrates the JSON export option as well. ![The Download menu provides Apache Ossie export options in YAML and JSON.](https://o6xswp5m6ilbks2z.public.blob.vercel-storage.com/blog-2d299a94af0649b656f7fbf62fda8c21647c52cdb65ef9ed325dd7b87a81b462.webp) Figure: The Download menu provides Apache Ossie export options in YAML and JSON. The completion dialog confirms the download and displays the warning **Column types are omitted from this Apache Ossie export.** Review that omission against the requirements of the application that will consume the model. ![The export completes successfully and reports that column types are omitted from the Apache Ossie export.](https://o6xswp5m6ilbks2z.public.blob.vercel-storage.com/blog-6d7b9761239a7bbe796730cc5554dd405cba62556d23362f427ec9e5bbc20b2e.webp) Figure: The export completes successfully and reports that column types are omitted from the Apache Ossie export. #### **Inspect the exported mappings** Open the downloaded YAML file. The video shows an Apache Ossie 0.1.1 document with a `semantic_model` entry named `puppygraph` and five datasets, one for each node type. For example, `Customer` maps to `shop.retail.customers`, uses `customer_id` as its primary key, and exposes source columns through `ANSI_SQL` field expressions. The graph edges become Ossie relationships with `from`, `to`, `from_columns`, and `to_columns`. For example, `PLACED_BY` connects `Order` to `Customer` through `customer_id`; `PART_OF` connects `OrderItem` to `Order` through `order_id`. ![The exported relationships preserve the source and target datasets and the columns that join them.](https://o6xswp5m6ilbks2z.public.blob.vercel-storage.com/blog-9c8495153535eaaf08549cfbe4fae7280d9556c7dd42d6327cb91d8d6bf77dde.webp) Figure: The exported relationships preserve the source and target datasets and the columns that join them. This workflow generates reusable source mappings and relationships from the graph schema. Business metrics still need explicit definitions. Before relying on the exported model, validate it against the schema for its document version and test the required fields and relationships in the receiving application. Watch the complete demonstration below: [Watch on YouTube: Instant Apache Ossie Model Generation | Auto-Ontology Feature Demo](https://www.youtube.com/watch?v=mG4YcQZ_UII) [Get Started with PuppyGraph for FREE](https://www.puppygraph.com/download-confirmation) ## Conclusion Apache Ossie gives data teams a common format for exchanging semantic definitions across tools. Its practical value comes from reusing models, making differences visible, and giving analytics and AI applications a shared description of business data. Adoption starts with a concrete producer, consumer, and specification version. Validate the artifact, inspect conversion losses, and compare query results. AI-assisted graph modeling followed by Ossie export can reduce manual work from source tables to a reusable model, while business ownership and consumer testing establish whether it is fit for the intended use. Try the forever-free [PuppyGraph Developer Edition](https://www.puppygraph.com/download-confirmation) and [book a demo](https://www.puppygraph.com/book-demo) with the team to see how openCypher and Gremlin queries connect entities across warehouse and lakehouse tables, with no graph-specific ETL, and how AI-assisted graph modeling and Ossie export make those mappings reusable.