Apache Ossie Ontology Specification and Core Logical Layer: Architecture Explained

Apache Ossie separates its metadata architecture into two complementary layers: the Ontological Layer, which defines business concepts in ontology/ontology.md, and the Core Logical Layer, which specifies analytical datasets in 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 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, 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):

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):

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	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 defines concepts, relationships, and mappings using constructs like Concept, Relationship, and ConceptMapping.
• The Core Metadata Specification in 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 specification, independent of any storage technology. The Logical Layer, defined in 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 within the apache/ossie repository, defining concepts and relationships. The Core Metadata Specification resides in 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.

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