# Apache Ossie Ontology Specification and Core Logical Layer: Architecture Explained

> Explore the Apache Ossie ontology specification and core logical layer architecture. Understand how these layers define business concepts and analytical datasets, linked by ontology mappings.

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

---

**Apache Ossie separates its metadata architecture into two complementary layers: the Ontological Layer, which defines business concepts in [`ontology/ontology.md`](https://github.com/apache/ossie/blob/main/ontology/ontology.md), and the Core Logical Layer, which specifies analytical datasets in [`core-spec/spec.md`](https://github.com/apache/ossie/blob/main/core-spec/spec.md), bridged through ontology mappings that translate logical fields into semantic objects.**

Apache Ossie is an open-source framework designed to unify data semantics across disparate analytics tools. Understanding the relationship between the Ossie ontology specification and its core logical layer is critical for implementing vendor-agnostic data models that maintain business meaning while supporting practical query execution. This architectural separation allows enterprises to define canonical business concepts independently from the physical and logical structures that power their reports and AI applications.

## The Two-Layer Architecture

Apache Ossie explicitly distinguishes between *what* data means in business terms and *how* that data is structured for analysis. This separation creates a flexible abstraction where business vocabulary remains stable even as underlying data sources evolve.

### Ontological Layer: Business Concept Modeling

The Ontological Layer captures enterprise business concepts, relationships, and rules in a implementation-agnostic manner. According to the [`ontology/ontology.md`](https://github.com/apache/ossie/blob/main/ontology/ontology.md) file, this layer defines:

- **Concept types** (`EntityType` or `ValueType`) representing business objects like `Person` or `Salary`
- **Relationship schemas** with roles, multiplicity constraints, and verbalizations
- **Derivation rules** and `requires` constraints that enforce business logic
- **Ontology mappings** that declare how logical data populates these concepts

This layer operates at the *concept level*, focusing on canonical domain entities rather than database tables. It enables consistent vocabulary sharing across SQL engines, AI assistants, and downstream analytics platforms.

### Core Logical Layer: Analytical Implementation

The Core Logical Layer, defined in [`core-spec/spec.md`](https://github.com/apache/ossie/blob/main/core-spec/spec.md), describes the analytical structure consumed by reporting tools and AI systems. This layer includes:

- **Semantic models** as top-level containers
- **Datasets** with `source` attributes pointing to physical tables or views
- **Fields** with dialect-specific expressions (ANSI_SQL, etc.)
- **Metrics** containing aggregate expressions like `SUM(orders.amount)`
- **Logical relationships** representing foreign-key links between datasets

Unlike the ontological layer, the logical layer works at the *dataset level*, providing query-ready schemas that tools can execute directly against data warehouses.

## Bridging the Layers: Ontology Mappings

The relationship between these layers is established through **ontology mappings** defined in the Ontology Specification. These mappings serve as the translation mechanism between logical data structures and business semantics.

**Concept mappings** declare how values from logical fields instantiate ontology objects. For example, a mapping might specify that the logical field `ORDERS.ORDER_ID` populates the ontology concept `Order`.

**Link mappings** connect logical field expressions to ontology relationships. This allows the system to assert that `ORDERS.AMOUNT` participates in the `has_amount` relationship between `Order` and `MonetaryAmount` concepts.

## Practical Implementation Example

Consider an e-commerce analytics scenario. The logical layer defines how to access and compute data, while the ontological layer defines what that data represents:

**Logical Layer** ([`core-spec/spec.md`](https://github.com/apache/ossie/blob/main/core-spec/spec.md)):

```yaml
datasets:
  - name: orders
    source: sales.public.orders
    primary_key: [order_id]
    fields:
      - name: order_date
        expression:
          dialects:
            - dialect: ANSI_SQL
              expression: order_date
        datatype: Date
        dimension:
          is_time: true
      - name: amount
        expression:
          dialects:
            - dialect: ANSI_SQL
              expression: amount
metrics:
  - name: total_revenue
    expression:
      dialects:
        - dialect: ANSI_SQL
          expression: SUM(orders.amount)
    datatype: Decimal

```

**Ontological Layer** ([`ontology/ontology.md`](https://github.com/apache/ossie/blob/main/ontology/ontology.md)):

```yaml
ontology:
  - concept: Order
    type: EntityType
    identify_by: [nr]
    relationships:
      - name: nr
        roles:
          - concept: OrderNumber
        multiplicity: OneToOne
        verbalizes: [ "{Order} is identified by {OrderNumber}" ]
      - name: has_amount
        roles:
          - concept: MonetaryAmount
        verbalizes: [ "{Order} has amount {MonetaryAmount}" ]
concept_mappings:
  - concept: Order
    object_mappings:
      - expression: ORDERS.ORDER_ID
    link_mappings:
      - object_mapping:
          concept: MonetaryAmount
          expression: ORDERS.AMOUNT
        relationship: has_amount

```

The first block defines *how* to query revenue data, while the second defines *what* an Order and its amount mean in business terms, along with the mapping that connects the logical `amount` field to the ontological `MonetaryAmount` concept.

## Key Architectural Differences

| Aspect | Ontological Layer | Core Logical Layer |
|--------|-------------------|-------------------|
| **Specification File** | [`ontology/ontology.md`](https://github.com/apache/ossie/blob/main/ontology/ontology.md) | [`core-spec/spec.md`](https://github.com/apache/ossie/blob/main/core-spec/spec.md) |
| **Granularity** | Concept-level (entities, value types) | Dataset-level (tables, fields, views) |
| **Purpose** | Business semantics and relationships | Analytical structure for query execution |
| **Storage Reference** | Implementation-agnostic | References physical sources via `source` attribute |
| **Key Constructs** | `Concept`, `Relationship`, `ConceptMapping` | `SemanticModel`, `Dataset`, `Field`, `Metric` |

## Summary

- Apache Ossie maintains a strict separation between the **Ontological Layer** (business meaning) and the **Core Logical Layer** (analytical structure).
- The Ontology Specification in [`ontology/ontology.md`](https://github.com/apache/ossie/blob/main/ontology/ontology.md) defines concepts, relationships, and mappings using constructs like `Concept`, `Relationship`, and `ConceptMapping`.
- The Core Metadata Specification in [`core-spec/spec.md`](https://github.com/apache/ossie/blob/main/core-spec/spec.md) defines queryable datasets, fields, and metrics using constructs like `SemanticModel`, `Dataset`, and `Field`.
- **Ontology mappings** bridge these layers by declaring how logical field expressions populate ontology objects and relationships.
- This architecture enables vendor-agnostic business vocabularies while supporting concrete, dialect-specific query execution.

## Frequently Asked Questions

### What is the difference between the Ontological Layer and the Logical Layer in Apache Ossie?

The Ontological Layer defines business concepts like entities and relationships in the [`ontology.md`](https://github.com/apache/ossie/blob/main/ontology.md) specification, independent of any storage technology. The Logical Layer, defined in [`core-spec/spec.md`](https://github.com/apache/ossie/blob/main/core-spec/spec.md), describes analytical datasets, fields, and metrics that reference physical data sources and are consumed by BI tools. The ontological layer answers "what does this data mean," while the logical layer answers "how do I query this data."

### How do ontology mappings connect logical fields to business concepts?

Ontology mappings use `concept_mappings` and `link_mappings` declarations in the Ontology Specification to declare translations between logical layer expressions and ontological objects. For example, a mapping might specify that the logical expression `ORDERS.AMOUNT` populates the `MonetaryAmount` concept linked to `Order` via the `has_amount` relationship.

### Where are the Ontology Specification and Core Metadata Specification located?

The Ontology Specification resides in [`ontology/ontology.md`](https://github.com/apache/ossie/blob/main/ontology/ontology.md) within the apache/ossie repository, defining concepts and relationships. The Core Metadata Specification resides in [`core-spec/spec.md`](https://github.com/apache/ossie/blob/main/core-spec/spec.md), defining semantic models, datasets, fields, and metrics. These files represent the authoritative source for Ossie's two-layer architecture.

### Why does Apache Ossie separate these two layers?

This separation allows business stakeholders to define stable, canonical vocabularies (ontologies) while data engineers evolve the underlying logical models and physical data sources. It prevents changes in database schemas or query dialects from breaking business semantics, and enables the same business concepts to be mapped across multiple different physical data implementations.