Ontological Layer vs Logical Layer in Apache Ossie: Architecture Distinctions

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 and 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), 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)—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, 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:

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 defines the corresponding business concepts and mappings:

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) defines business concepts, value types, and relationships using Concept and Relationship constructs, remaining independent of physical storage.
• The logical layer (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. The logical layer captures analytical structure—datasets, fields, and metrics for BI tools—defined in 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), 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 without immediate corresponding datasets in the logical layer, though practical analytics require the logical layer to provide queryable datasets that reference physical data sources.

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