Layers of Apache Ossie Architecture: The Semantic Stack Explained

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, 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, 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 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, 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 demonstrates how a semantic model integrates the hub, logical, and physical layers:

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 – Defines the semantic model JSON/YAML schema that serves as the hub of the architecture
• core-spec/expression_language.md – Explains the ontology and logical layers and the expression language operating at the logical layer
• docs/index.md – Provides the hub-and-spoke architectural overview and the semantic layer's central role
• converters/README.md – Describes how converters implement the hub-and-spoke pattern, reinforcing layer separation
• 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, 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, which describes it as a future metadata bridge that will handle logical-to-physical translation concerns such as schema evolution and type conversion.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}