# Ontological Layer vs Logical Layer in Apache Ossie: Architecture Distinctions

> Understand Apache Ossie's ontological vs logical layer distinctions. Discover how the ontological layer maps business concepts and the logical layer prepares data for analysis.

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

---

**Apache Ossie’s ontological layer captures vendor-agnostic business concepts and relationships, while its logical layer defines query-ready datasets and metrics for analytical tools.**

Apache Ossie separates data-modeling concerns into two complementary specifications that bridge business semantics with analytical execution. Understanding the distinctions between the **ontological layer** and **logical layer** is essential for building canonical data models that maintain semantic consistency across SQL engines, BI platforms, and AI assistants. These layers are defined in [`ontology/ontology.md`](https://github.com/apache/ossie/blob/main/ontology/ontology.md) and [`core-spec/spec.md`](https://github.com/apache/ossie/blob/main/core-spec/spec.md) respectively, and are linked through explicit mapping constructs.

## Core Purpose and Design Philosophy

### Ontological Layer: Business Concept Modeling

The ontological layer establishes a **canonical, domain-centric vocabulary** that describes enterprise entities, value types, and their relationships independent of any storage implementation. Defined in [[`ontology/ontology.md`](https://github.com/apache/ossie/blob/main/ontology/ontology.md)](https://github.com/apache/ossie/blob/main/ontology/ontology.md), this layer answers *what* the data means in business terms—such as defining a `Person` entity, a `Salary` value type, or a `Person.earns` relationship. It provides a consistent vocabulary that can be shared across heterogeneous tools without vendor lock-in.

### Logical Layer: Analytical Structure

The logical layer—formally the **Core Metadata Specification** in [[`core-spec/spec.md`](https://github.com/apache/ossie/blob/main/core-spec/spec.md)](https://github.com/apache/ossie/blob/main/core-spec/spec.md)—describes the *analytical structure* of data consumed by reporting, BI, or AI tools. This layer defines concrete **datasets** (tables or views), **fields**, **metrics**, and logical relationships using identifiers that reference physical sources only via the `source` attribute. It supplies the query-ready schema that tools execute, such as `SELECT SUM(amount) FROM orders`.

## Key Constructs and Granularity

The two layers operate at different levels of abstraction, utilizing distinct construct types:

**Ontological Layer Constructs:**
- **`Concept`** – Represents either an `EntityType` (e.g., `Order`) or `ValueType` (e.g., `MonetaryAmount`)
- **`Relationship`** – Defines roles, multiplicity constraints (e.g., `OneToOne`), and verbalizations between concepts
- **`Ontology`** – A collection container for concepts and relationships
- **`ConceptMapping`** / **`LinkMapping`** – Declares how logical field expressions populate ontology objects or relationship links

**Logical Layer Constructs:**
- **`SemanticModel`** – Top-level container for analytical definitions
- **`Dataset`** – Named analytical object with a `source` attribute pointing to physical tables or views, plus primary/unique key definitions
- **`Field`** – Column definitions with expressions, datatypes, and dimension flags (e.g., `is_time`)
- **`Metric`** – Aggregate expressions (e.g., `SUM(orders.amount)`) for analytical consumption
- **`Relationship`** – Logical foreign-key links between datasets

**Granularity Distinction:**
- The ontological layer works at the **concept level** (e.g., a `Person` entity or `Salary` value type).
- The logical layer works at the **dataset level** (e.g., an `orders` dataset with a `customer_id` field).

## Mapping Mechanism Between Layers

The layers connect through **ontology mappings** that translate logical field expressions into ontology objects. The logical layer directly references physical storage via the `source` attribute on datasets, while the ontological layer remains storage-agnostic. 

In [`ontology/ontology.md`](https://github.com/apache/ossie/blob/main/ontology/ontology.md), `concept_mappings` declare how values from logical fields are transformed into ontology objects or links. For example, a logical field `ORDERS.AMOUNT` maps to the ontological concept `MonetaryAmount` through a `link_mapping` that specifies the relationship `has_amount`. This separation ensures that business semantics remain stable even when underlying physical schemas evolve.

## Practical Implementation Examples

The following YAML illustrates the logical layer defining a dataset and metric in [`spec.md`](https://github.com/apache/ossie/blob/main/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
        description: Order date
      - name: amount
        expression:
          dialects:
            - dialect: ANSI_SQL
              expression: amount
metrics:
  - name: total_revenue
    expression:
      dialects:
        - dialect: ANSI_SQL
          expression: SUM(orders.amount)
    datatype: Decimal
    description: Total revenue across all orders

```

This configuration describes *where* data lives and *how* to compute metrics, but carries no inherent business meaning.

Conversely, the ontological layer in [`ontology.md`](https://github.com/apache/ossie/blob/main/ontology.md) defines the corresponding business concepts and mappings:

```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

```

This second block assigns business semantics to the logical fields, declaring that `ORDERS.AMOUNT` represents the `MonetaryAmount` concept in the context of an `Order` entity.

## Summary

- **The ontological layer** ([`ontology/ontology.md`](https://github.com/apache/ossie/blob/main/ontology/ontology.md)) defines business concepts, value types, and relationships using `Concept` and `Relationship` constructs, remaining independent of physical storage.
- **The logical layer** ([`core-spec/spec.md`](https://github.com/apache/ossie/blob/main/core-spec/spec.md)) defines analytical datasets, fields, and metrics using `SemanticModel` and `Dataset` constructs, referencing physical sources via the `source` attribute.
- **Granularity differs** between concept-level modeling (ontological) and dataset-level modeling (logical).
- **Mapping occurs** through `concept_mappings` and `link_mappings` that bind logical field expressions to ontological objects, enabling consistent interpretation across platforms.

## Frequently Asked Questions

### How does the ontological layer differ from the logical layer in Apache Ossie?

The ontological layer captures *business semantics*—entities like `Person` or `Order` and their relationships—using constructs defined in [`ontology/ontology.md`](https://github.com/apache/ossie/blob/main/ontology/ontology.md). The logical layer captures *analytical structure*—datasets, fields, and metrics for BI tools—defined in [`core-spec/spec.md`](https://github.com/apache/ossie/blob/main/core-spec/spec.md). While the ontological layer is storage-agnostic, the logical layer explicitly references physical tables through the `source` attribute.

### What file defines the ontological layer in Ossie?

The ontological layer is specified in [[`ontology/ontology.md`](https://github.com/apache/ossie/blob/main/ontology/ontology.md)](https://github.com/apache/ossie/blob/main/ontology/ontology.md), which defines `Concept` types, `Relationship` schemas, multiplicities, and the `concept_mappings` used to link business concepts to logical fields.

### How are logical datasets mapped to ontological concepts?

Logical datasets map to ontological concepts through **ontology mappings** declared in the `concept_mappings` section of the ontology specification. These mappings use `object_mappings` to bind logical field expressions (e.g., `ORDERS.ORDER_ID`) to ontology objects, and `link_mappings` to establish relationships between concepts based on logical field values.

### Can the ontological layer exist independently of the logical layer?

Yes. The ontological layer is designed as a **canonical vocabulary** independent of any particular storage or analytical implementation. Organizations can define business concepts and relationships in [`ontology/ontology.md`](https://github.com/apache/ossie/blob/main/ontology/ontology.md) without immediate corresponding datasets in the logical layer, though practical analytics require the logical layer to provide queryable datasets that reference physical data sources.