# How to Validate Ossie Semantic Models: Tools and Methods Explained

> Discover tools and methods to validate Ossie semantic models. Learn about the Python validator in the Apache Ossie repository for comprehensive checks and specification conformance.

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

---

**The Apache Ossie repository provides a stand-alone Python validator in [`validation/validate.py`](https://github.com/apache/ossie/blob/main/validation/validate.py) that performs JSON-Schema validation, uniqueness checks, reference validation, and SQL syntax parsing to ensure semantic model files conform to the OSSIE Open Semantic Interface (OSI) specification.**

Apache Ossie is an open-source semantic modeling framework that standardizes interfaces for data analytics platforms. When you validate Ossie semantic models, you verify that YAML or JSON definitions conform to the official OSSIE schema and maintain internal consistency across datasets, fields, and relationships.

## Core Validation Tools in the validation/ Directory

The primary validation engine resides in [`validation/validate.py`](https://github.com/apache/ossie/blob/main/validation/validate.py). This module exposes four key validation functions that compose a complete semantic model verification pipeline.

### JSON-Schema Validation

The `validate_schema` function checks structural conformity against the canonical OSSIE Open Semantic Interface (OSI) definition. It uses **jsonschema** v4+ to verify data types, required fields, and enumerated values defined in [`core-spec/osi-schema.json`](https://github.com/apache/ossie/blob/main/core-spec/osi-schema.json).

### Semantic Uniqueness Checks

Duplicate identifiers break semantic integrity. The `validate_unique_names` function detects collisions in dataset names, field names, metric names, and relationship names within a single model file.

### Reference Integrity Validation

Relationships must point to existing datasets. The `validate_references` function traverses all relationship definitions and verifies that every target dataset reference resolves to a defined entity in the model.

### SQL Syntax Validation

Field and metric expressions require syntactic validation. The `validate_sql` function uses **sqlglot** to parse SQL expressions for supported dialects including ANSI-SQL, Snowflake, Databricks, and BigQuery. Unsupported dialects such as MDX, Tableau, and MAQL are skipped gracefully rather than throwing errors.

## Running the Validator from the Command Line

Execute the validator directly against semantic model files using Python:

```bash

# Validate against the bundled OSI schema

python validation/validate.py examples/tpcds_semantic_model.yaml

# Validate with a custom schema file

python validation/validate.py my_model.yaml --schema path/to/custom-schema.json

```

The script outputs a concise PASS/FAIL status and enumerates specific errors with line references.

## Programmatic Validation in Python

Integrate validation into data pipelines by importing functions from [`validation/validate.py`](https://github.com/apache/ossie/blob/main/validation/validate.py):

```python
import json
import yaml
from pathlib import Path
from validation.validate import (
    validate_schema,
    validate_unique_names,
    validate_references,
    validate_sql,
)

# Load model and schema

model_path = Path("examples/flights.yaml")
with open(model_path) as f:
    model = yaml.safe_load(f)

schema_path = Path("core-spec/osi-schema.json")
with open(schema_path) as f:
    schema = json.load(f)

# Execute validation suite

errors = []
errors.extend(validate_schema(model, schema))
errors.extend(validate_unique_names(model))
errors.extend(validate_references(model))
errors.extend(validate_sql(model))

# Report results

if errors:
    for error in errors:
        print(error)
else:
    print("Model is valid")

```

This approach allows custom error handling, logging integration, and automated testing workflows.

## Validation Artifacts and Dependencies

The validator relies on three core artifacts located outside the `validation/` directory.

### OSI Schema Definition

The file [`core-spec/osi-schema.json`](https://github.com/apache/ossie/blob/main/core-spec/osi-schema.json) contains the canonical JSON-Schema definition that governs structural validation. This specification defines required properties, data types, and validation constraints for all OSSIE semantic model files.

### Ontology Vocabulary

Semantic terms derive from [`ontology/ontology.json`](https://github.com/apache/ossie/blob/main/ontology/ontology.json), which provides the controlled vocabulary referenced during validation. This ensures consistent terminology across datasets and metrics.

### Example Models

Reference implementations in `examples/` provide valid test cases. Files such as [`examples/tpcds_semantic_model.yaml`](https://github.com/apache/ossie/blob/main/examples/tpcds_semantic_model.yaml) and [`examples/flights.yaml`](https://github.com/apache/ossie/blob/main/examples/flights.yaml) demonstrate proper structure and serve as regression tests for the validator.

## Future CLI Integration

The repository includes a command-line stub at [`cli/cmd/validate.go`](https://github.com/apache/ossie/blob/main/cli/cmd/validate.go) that implements the `ossie validate` subcommand. While currently a placeholder, this Go-based CLI can be extended to invoke the Python validator via subprocess calls, enabling a unified `ossie validate path/to/model.yaml` experience with rich error reporting.

## Summary

- The **Python validator** in [`validation/validate.py`](https://github.com/apache/ossie/blob/main/validation/validate.py) provides comprehensive semantic model verification through four specialized functions.
- **JSON-Schema validation** ensures structural conformity using [`core-spec/osi-schema.json`](https://github.com/apache/ossie/blob/main/core-spec/osi-schema.json) and the jsonschema library.
- **Semantic checks** include uniqueness validation for identifiers and reference integrity for relationships.
- **SQL parsing** via sqlglot validates expressions for ANSI-SQL, Snowflake, Databricks, and BigQuery dialects.
- **Programmatic integration** allows embedding validation into Python applications and CI/CD pipelines.
- A **Go CLI stub** at [`cli/cmd/validate.go`](https://github.com/apache/ossie/blob/main/cli/cmd/validate.go) provides the foundation for future unified command-line tooling.

## Frequently Asked Questions

### What validation steps does the Ossie semantic model validator perform?

The validator executes four distinct checks: JSON-Schema structural validation against the OSI specification, uniqueness verification for dataset and field names, reference integrity confirmation for relationships, and SQL syntax parsing for supported dialects. Each step is implemented as a separate function in [`validation/validate.py`](https://github.com/apache/ossie/blob/main/validation/validate.py) that can be run independently or composed into a complete validation pipeline.

### Which SQL dialects are supported by the Ossie validator?

According to the source code in [`validation/validate.py`](https://github.com/apache/ossie/blob/main/validation/validate.py), the validator supports ANSI-SQL, Snowflake, Databricks, and BigQuery through the sqlglot parsing library. Unsupported dialects including MDX, Tableau, and MAQL are intentionally skipped during validation to prevent false positives, allowing models targeting these platforms to pass validation while still checking structural integrity.

### Can I use the Ossie validator as a Python library?

Yes. Import the validation functions directly from [`validation/validate.py`](https://github.com/apache/ossie/blob/main/validation/validate.py) to integrate checks into existing Python applications. The functions `validate_schema`, `validate_unique_names`, `validate_references`, and `validate_sql` accept Python dictionaries representing the loaded model and return lists of error objects, enabling custom error handling and automated testing workflows.

### Is there a command-line interface for validating Ossie models?

Currently, the primary interface is the Python script [`validation/validate.py`](https://github.com/apache/ossie/blob/main/validation/validate.py) invoked directly. The repository includes a Go-based stub at [`cli/cmd/validate.go`](https://github.com/apache/ossie/blob/main/cli/cmd/validate.go) that implements the `ossie validate` command structure, but this requires extension to invoke the Python validation logic. Users can run `python validation/validate.py path/to/model.yaml` for immediate command-line validation.