# Ossie Semantic Model: Key Properties and Implementation Guide

> Explore the Ossie semantic model with its five key properties name description datasets relationships and metrics Understand how Ossie models translate business data for analytics platforms.

- Repository: [The Apache Software Foundation/ossie](https://github.com/apache/ossie)
- Tags: how-to-guide
- Published: 2026-07-19

---

**An Ossie semantic model defines business data structure through five core properties—`name`, `description`, `datasets`, `relationships`, and `metrics`—enabling translation between OSSIE-native constructs and external analytics platforms.**

The Apache Ossie project delivers a unified interoperability framework for converting between semantic layer formats. At its core, the Ossie semantic model provides a structured representation of logical tables, their relationships, and calculated measures that powers cross-platform analytics integration.

## Core Properties of the Ossie Semantic Model

The `SemanticModel` class is defined as a nested static class inside [`OsiModel.java`](https://github.com/apache/ossie/blob/main/OsiModel.java) at [`converters/polaris/src/main/java/org/apache/ossie/converter/polaris/model/OsiModel.java`](https://github.com/apache/ossie/blob/main/converters/polaris/src/main/java/org/apache/ossie/converter/polaris/model/OsiModel.java). According to the Apache Ossie source code, the model contains five essential properties that establish its structure and behavior.

### Metadata Properties (name and description)

Every semantic model requires a human-readable identifier stored in the **`name`** property (lines 53‑55), which serves as the primary reference for the model. The optional **`description`** property (lines 55‑57) provides free-form text explaining the model's business purpose and governance context.

### datasets (List<Dataset>)

The **`datasets`** property (lines 56‑58) contains a `List<Dataset>` representing the logical tables within the model. Each `Dataset` includes:

- `name` and `source` (physical table reference)
- Primary and unique key definitions
- A list of `Field` objects with dialect-specific expressions
- Optional custom extensions for platform-specific metadata

### relationships (List<Relationship>)

The **`relationships`** property (lines 57‑59) defines foreign-key-like links between datasets through a `List<Relationship>`. Each relationship specifies:

- A `name` for the relationship
- `from` and `to` dataset references
- Column mappings (`fromColumns` and `toColumns`) that establish join conditions

### metrics (List<Metric>)

The optional **`metrics`** property (lines 58‑60) stores calculated measures via `List<Metric>`. These reusable calculations attach to the model level and contain:

- A `name` and `description`
- One or more `DialectExpression` objects containing platform-specific formulas (e.g., SQL expressions like `SUM(amount)`)

## Programmatically Building an Ossie Semantic Model

The Apache Ossie repository provides fluent Java APIs for constructing semantic models imperatively. The following example demonstrates creating a complete model with datasets, relationships, and metrics:

```java
// Initialize the semantic model
OsiModel.SemanticModel sm = new OsiModel.SemanticModel();
sm.setName("sales");
sm.setDescription("Sales domain model");

// Configure a Dataset
OsiModel.Dataset orders = new OsiModel.Dataset();
orders.setName("orders");
orders.setSource("orders_table");
orders.setPrimaryKey(List.of("order_id"));
orders.setDescription("Customer orders");

// Add a field with SQL expression
OsiModel.Field orderId = new OsiModel.Field();
orderId.setName("order_id");
orderId.setDescription("Primary key");
orderId.setExpressions(
    List.of(new OsiModel.DialectExpression("SQL", "order_id"))
);
orders.setFields(List.of(orderId));
sm.setDatasets(List.of(orders));

// Define a Relationship between datasets
OsiModel.Relationship rel = new OsiModel.Relationship();
rel.setName("order_customer");
rel.setFrom("orders");
rel.setTo("customers");
rel.setFromColumns(List.of("customer_id"));
rel.setToColumns(List.of("id"));
sm.setRelationships(List.of(rel));

// Create a calculated Metric
OsiModel.Metric totalRevenue = new OsiModel.Metric();
totalRevenue.setName("total_revenue");
totalRevenue.setDescription("Sum of all order amounts");
totalRevenue.setExpressions(
    List.of(new OsiModel.DialectExpression("SQL", "SUM(amount)"))
);
sm.setMetrics(List.of(totalRevenue));

```

## Exporting and Importing Semantic Models

Once constructed, the Ossie semantic model integrates with platform-specific converters. The Polaris converter demonstrates this workflow:

```java
OsiModel model = new OsiModel();
model.setVersion("1.0");
model.setSemanticModels(List.of(sm));

OsiPolarisConverter converter = new OsiPolarisConverter();
converter.exportSemanticModel(sm);   // Generates Polaris-compatible YAML

```

## Key Implementation Files

Understanding the Ossie semantic model architecture requires familiarity with these core source files:

- **[`OsiModel.java`](https://github.com/apache/ossie/blob/main/OsiModel.java)** – Located at [`converters/polaris/src/main/java/org/apache/ossie/converter/polaris/model/OsiModel.java`](https://github.com/apache/ossie/blob/main/converters/polaris/src/main/java/org/apache/ossie/converter/polaris/model/OsiModel.java), this file defines the `SemanticModel` nested class along with supporting types including `Dataset`, `Relationship`, `Metric`, `Field`, and `CustomExtension`.

- **[`SemanticModelMappingHandler.java`](https://github.com/apache/ossie/blob/main/SemanticModelMappingHandler.java)** – Found in the Salesforce converter module at [`converters/salesforce/src/main/java/org/apache/ossie/converter/SemanticModelMappingHandler.java`](https://github.com/apache/ossie/blob/main/converters/salesforce/src/main/java/org/apache/ossie/converter/SemanticModelMappingHandler.java), this pipeline step maps OSSIE objects into semantic model instances during format conversion.

- **[`PolarisExporter.java`](https://github.com/apache/ossie/blob/main/PolarisExporter.java)** – Handles serialization of `SemanticModel` instances into Polaris-compatible YAML format for external analytics platforms.

- **[`PolarisImporter.java`](https://github.com/apache/ossie/blob/main/PolarisImporter.java)** – Parses YAML representations back into `OsiModel` and `SemanticModel` Java objects, enabling bidirectional conversion.

## Summary

- The Ossie semantic model consists of five core properties: `name`, `description`, `datasets`, `relationships`, and `metrics`.
- **Datasets** represent logical tables with fields, keys, and dialect-specific expressions.
- **Relationships** define foreign-key connections between datasets using column mappings.
- **Metrics** store calculated measures with platform-specific formulas.
- The `SemanticModel` class is nested within [`OsiModel.java`](https://github.com/apache/ossie/blob/main/OsiModel.java) in the Apache Ossie Polaris converter module.
- Programmatic construction uses standard Java setters, while `PolarisExporter` and `PolarisImporter` handle YAML serialization.

## Frequently Asked Questions

### What is the difference between an Ossie semantic model and a physical database schema?

An Ossie semantic model operates at the logical layer, defining business-friendly datasets, relationships, and metrics abstracted from physical storage. While a database schema describes actual tables and columns in a specific SQL dialect, the semantic model uses dialect-agnostic structures with optional dialect-specific expressions, enabling translation between different analytics platforms like Polaris and Salesforce.

### How do I add calculated fields to an Ossie semantic model?

Calculated fields are added through the `metrics` property, which accepts a `List<Metric>`. Each `Metric` object requires a `name`, optional `description`, and a list of `DialectExpression` objects containing the calculation formula. For SQL-based platforms, you would create a `DialectExpression` with the dialect identifier "SQL" and the appropriate aggregation function such as `SUM(amount)` or `COUNT(*)`.

### Can an Ossie semantic model contain multiple datasets?

Yes, the `datasets` property is defined as a `List<Dataset>`, allowing a single semantic model to contain numerous logical tables. Each dataset maintains its own fields, primary keys, and source references, while the `relationships` property links these datasets together to form a cohesive semantic layer suitable for complex analytical queries.

### Where is the SemanticModel class defined in the Apache Ossie repository?

The `SemanticModel` class is implemented as a nested static class inside [`OsiModel.java`](https://github.com/apache/ossie/blob/main/OsiModel.java), located at [`converters/polaris/src/main/java/org/apache/ossie/converter/polaris/model/OsiModel.java`](https://github.com/apache/ossie/blob/main/converters/polaris/src/main/java/org/apache/ossie/converter/polaris/model/OsiModel.java). This file also contains the related `Dataset`, `Relationship`, `Metric`, `Field`, and `CustomExtension` classes that comprise the complete semantic model hierarchy.