Ossie Semantic Model: Key Properties and Implementation Guide

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

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)

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)

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:

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

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 – Located at 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 – Found in the Salesforce converter module at 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 – Handles serialization of SemanticModel instances into Polaris-compatible YAML format for external analytics platforms.

• 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 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, located at 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.

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