# Layers of Apache Ossie Architecture: The Semantic Stack Explained

> Explore the five semantic layers of Apache Ossie architecture: Semantic Hub Ontology Logical Physical and Mapping. Understand how Ossie separates business meaning from physical storage.

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

---

**Apache Ossie organizes data interoperability into five concentric semantic layers—Semantic (Hub), Ontology, Logical, Physical, and Mapping—that cleanly separate business meaning from physical storage implementation.**

Apache Ossie (Open Semantic Interchange Engine) implements a hub-and-spoke architecture designed to decouple business semantics from underlying data storage. Understanding the layers of Apache Ossie architecture is essential for developers building converters and semantic models that must interoperate across disparate database systems. The architecture organizes functionality into distinct strata that progress from abstract business concepts down to concrete database tables, with each layer defined in the `core-spec/` directory of the `apache/ossie` repository.

## The Five Layers of Apache Ossie Architecture

### Semantic (Hub) Layer

The **Semantic (Hub) Layer** represents the top-level Ossie core specification that defines a complete semantic model including datasets, relationships, fields, and metrics. This layer acts as the universal interchange format that all converters read from and write to, serving as the central hub in the hub-and-spoke architecture. According to [`core-spec/spec.md`](https://github.com/apache/ossie/blob/main/core-spec/spec.md), this layer provides the canonical JSON/YAML schema that enables disparate systems to share semantic definitions without sharing physical storage.

### Ontology Layer

The **Ontology Layer** sits above the logical layer and provides a high-level abstraction of business concepts such as entities and relationships. This optional layer aligns with modeling languages like OWL, Relational AI’s (Py)Rel, and Goldman Sachs Legend to provide a canonical vocabulary for concepts like *Customer*, *Order*, or *Product*. As documented in [`core-spec/expression_language.md`](https://github.com/apache/ossie/blob/main/core-spec/expression_language.md), the ontology layer maps business concepts that can be reused across multiple logical models, enabling enterprise-wide semantic consistency.

### Logical Layer

The **Logical Layer** maps directly to databases or other physical data sources and corresponds to traditional BI semantic models. This layer describes datasets (tables or views), fields, and metrics in terms of SQL-compatible expressions that can be executed by underlying query engines. The [`core-spec/expression_language.md`](https://github.com/apache/ossie/blob/main/core-spec/expression_language.md) file specifies that this layer "maps directly to the databases and physical layer," containing the portable SQL dialect expressions that applications actually query against.

### Physical Layer

The **Physical Layer** comprises the actual storage objects—tables, views, and files—that provide raw data for the logical layer. While implicitly referenced throughout the specification via the `source` field of dataset definitions, this layer represents the concrete database objects where data physically resides. The logical layer references these physical sources while maintaining independence from specific storage implementations.

### Mapping Layer (Planned)

The **Mapping Layer** is a planned thin metadata layer that will bridge the logical layer to the physical layer, handling naming conventions, type conversion, and schema evolution concerns. According to [`ROADMAP.md`](https://github.com/apache/ossie/blob/main/ROADMAP.md), this layer will enable robust translation between logical definitions and physical data structures without changing execution semantics, providing greater flexibility when physical schemas change underneath stable logical models.

## How the Layers Interact in Practice

The layers operate as a pipeline where business concepts flow downward and data flows upward. The following YAML snippet from [`core-spec/spec.md`](https://github.com/apache/ossie/blob/main/core-spec/spec.md) demonstrates how a semantic model integrates the hub, logical, and physical layers:

```yaml
semantic_model:
  - name: sales_analytics
    description: Sales and customer analytics model
    datasets:
      - name: orders                # Logical dataset (logical layer)

        source: sales.public.orders # Physical table (physical layer)

        primary_key: [order_id]
        fields:
          - name: order_id
            expression:
              dialects:
                - dialect: ANSI_SQL
                  expression: order_id
          - name: order_date
            expression:
              dialects:
                - dialect: ANSI_SQL
                  expression: order_date
            dimension:
              is_time: true
    relationships:
      - name: orders_to_customers
        from: orders
        to: customers
        from_columns: [customer_id]
        to_columns: [id]            # Logical relationship (logical layer)

    metrics:
      - name: total_revenue
        expression:
          dialects:
            - dialect: ANSI_SQL
              expression: SUM(orders.amount)   # Logical metric (logical layer)

```

In this example:
- **`datasets`** define logical abstractions that reference physical sources via the `source` field
- **`fields`** contain ANSI SQL expressions representing the logical layer's portable query language
- **`relationships`** and **`metrics`** operate entirely at the logical layer, joining datasets and defining calculations
- An optional **ontology layer** could provide canonical definitions for `Customer` and `Order` concepts reused across multiple such models

## Key Implementation Files

Understanding the architecture requires examining these specific files in the `apache/ossie` repository:

- **[`core-spec/spec.md`](https://github.com/apache/ossie/blob/main/core-spec/spec.md)** – Defines the semantic model JSON/YAML schema that serves as the hub of the architecture
- **[`core-spec/expression_language.md`](https://github.com/apache/ossie/blob/main/core-spec/expression_language.md)** – Explains the ontology and logical layers and the expression language operating at the logical layer
- **[`docs/index.md`](https://github.com/apache/ossie/blob/main/docs/index.md)** – Provides the hub-and-spoke architectural overview and the semantic layer's central role
- **[`converters/README.md`](https://github.com/apache/ossie/blob/main/converters/README.md)** – Describes how converters implement the hub-and-spoke pattern, reinforcing layer separation
- **[`ROADMAP.md`](https://github.com/apache/ossie/blob/main/ROADMAP.md)** – Documents the planned mapping layer and future ontology enhancements

## Summary

Apache Ossie achieves clean separation of concerns through its layered semantic architecture:

- The **Semantic (Hub) Layer** provides the universal interchange format for all converters
- The **Ontology Layer** offers optional, reusable business concept models sitting above logical definitions
- The **Logical Layer** contains portable, SQL-based definitions that applications query directly
- The **Physical Layer** supplies the concrete data sources referenced by logical datasets
- The **Mapping Layer** (planned) will bridge logical and physical layers to handle schema evolution

This architecture enables organizations to maintain stable business semantics while swapping underlying database technologies or evolving physical schemas.

## Frequently Asked Questions

### What is the purpose of the hub-and-spoke architecture in Apache Ossie?

The hub-and-spoke design centralizes semantic definitions in the **Semantic (Hub) Layer**, allowing any number of converters (the "spokes") to read from and write to a single canonical format. This eliminates the need for pairwise integrations between systems and ensures that business semantics remain consistent across the entire data ecosystem.

### How does the Ontology Layer differ from the Logical Layer?

The **Ontology Layer** operates at a higher level of abstraction, defining reusable business concepts like *Customer* or *Product* that can span multiple models, while the **Logical Layer** maps directly to database objects and contains executable SQL expressions. According to [`core-spec/expression_language.md`](https://github.com/apache/ossie/blob/main/core-spec/expression_language.md), the ontology layer sits above the logical layer and aligns with knowledge representation standards like OWL.

### Can Apache Ossie work with existing databases without migration?

Yes. The **Logical Layer** references existing physical tables and views through the `source` field, allowing Ossie to provide a semantic layer over existing infrastructure without requiring data migration. The planned **Mapping Layer** will further simplify integration by handling naming mismatches and type conversions between logical definitions and existing physical schemas.

### Where is the Mapping Layer implemented in the current codebase?

The **Mapping Layer** is not yet fully implemented. It is documented as a planned feature in [`ROADMAP.md`](https://github.com/apache/ossie/blob/main/ROADMAP.md), which describes it as a future metadata bridge that will handle logical-to-physical translation concerns such as schema evolution and type conversion.