# How to Validate Ossie Semantic Models: The Complete Python Validation Toolkit

> Explore the Python validation toolkit for Ossie semantic models. Validate schema compliance, uniqueness, referential integrity, and SQL syntax efficiently.

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

---

**Ossie ships with a stand-alone Python validator that checks semantic model files against the official OSSIE schema and performs semantic checks for uniqueness, referential integrity, and SQL syntax.**

The Apache Ossie project provides a comprehensive validation toolkit to ensure your semantic models conform to the Open Semantic Interface (OSI) specification. When you need to validate Ossie semantic models, the project offers a robust Python-based solution that integrates structural schema validation with deep semantic analysis.

## The Stand-Alone Python Validator

Ossie's primary validation tool resides in [`validation/validate.py`](https://github.com/apache/ossie/blob/main/validation/validate.py). This module exposes four core validation functions that collectively ensure model integrity: `validate_schema`, `validate_unique_names`, `validate_references`, and `validate_sql`.

### JSON-Schema Validation

The `validate_schema` function uses **jsonschema** v4+ to verify that your YAML or JSON files conform to the canonical OSI structure. It checks data types, required fields, and enumerated values against the official schema definition stored in [`core-spec/osi-schema.json`](https://github.com/apache/ossie/blob/main/core-spec/osi-schema.json).

### Semantic Uniqueness Checks

Duplicate identifiers within a model can cause ambiguous references. The `validate_unique_names` function detects duplicate dataset, field, metric, and relationship names, ensuring each entity has a unique identifier within the semantic model scope.

### Referential Integrity Validation

Relationships must point to existing datasets to maintain model coherence. The `validate_references` function traverses all relationship definitions and verifies that every target dataset exists within the model, preventing dangling references.

### SQL Syntax Validation

For models containing calculated fields or metrics, the `validate_sql` function parses expressions using **sqlglot**. It validates syntax for ANSI-SQL, Snowflake, Databricks, and BigQuery dialects. Unsupported dialects such as MDX, Tableau, and MAQL are gracefully skipped rather than rejected.

## Core Data Artifacts

The validator relies on three critical artifacts located in the repository root:

- **[`core-spec/osi-schema.json`](https://github.com/apache/ossie/blob/main/core-spec/osi-schema.json)** — The canonical JSON-Schema definition governing OSI structure and data types.
- **[`ontology/ontology.json`](https://github.com/apache/ossie/blob/main/ontology/ontology.json)** — The semantic vocabulary defining valid terms and relationships.
- **`examples/*.yaml`** — Sample models including [`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) for testing validation logic.

## Practical Usage Examples

### Command-Line Validation

Execute the validator directly against semantic model files using the Python script:

```bash

# Basic validation against the bundled schema

python validation/validate.py examples/tpcds_semantic_model.yaml

# Use a custom schema file for extended or forked versions

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

```

The script outputs a concise PASS/FAIL message with detailed error listings for any violations detected.

### Programmatic Integration

Import the validation functions directly into Python workflows for custom data pipelines:

```python
import json, 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 checks

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

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

```

This approach allows you to compose validation steps within larger automation frameworks or CI/CD pipelines.

### Go CLI Wrapper

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` command. While currently a placeholder, this Go interface can be extended to invoke the Python validator via subprocess calls, providing a unified CLI experience for users who prefer native binaries over direct Python execution.

## Summary

- **Primary validation tool**: The [`validation/validate.py`](https://github.com/apache/ossie/blob/main/validation/validate.py) script provides comprehensive checking through four specialized functions.
- **Schema compliance**: Validates against [`core-spec/osi-schema.json`](https://github.com/apache/ossie/blob/main/core-spec/osi-schema.json) using jsonschema v4+.
- **Semantic integrity**: Ensures unique names and valid references across datasets, fields, and relationships.
- **SQL validation**: Parses expressions for ANSI-SQL, Snowflake, Databricks, and BigQuery using sqlglot.
- **Flexible usage**: Available as both a command-line utility and a programmatic Python API.

## Frequently Asked Questions

### What file formats does the Ossie validator support?

The validator accepts both YAML and JSON semantic model files. The [`validate.py`](https://github.com/apache/ossie/blob/main/validate.py) script automatically parses these formats before applying the JSON-Schema validation and semantic checks defined in the OSI specification.

### Which SQL dialects are validated 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 explicitly supports ANSI-SQL, Snowflake, Databricks, and BigQuery dialects through sqlglot parsing. It intentionally skips validation for MDX, Tableau, and MAQL dialects, allowing those expressions to pass without syntax checking.

### Can I use the validator outside of the Ossie CLI?

Yes. While the Go-based CLI at [`cli/cmd/validate.go`](https://github.com/apache/ossie/blob/main/cli/cmd/validate.go) provides a stub for future integration, you can currently run the Python validator directly via command line or import the validation functions into your own Python applications. The modular design of [`validate.py`](https://github.com/apache/ossie/blob/main/validate.py) allows selective execution of individual validation steps.

### Where is the official OSI schema definition located?

The canonical JSON-Schema definition resides at [`core-spec/osi-schema.json`](https://github.com/apache/ossie/blob/main/core-spec/osi-schema.json) in the repository root. This file serves as the single source of truth for structural validation and is used by the `validate_schema` function to verify that models conform to the Open Semantic Interface specification.