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

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. 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.

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 — The canonical JSON-Schema definition governing OSI structure and data types.
• ontology/ontology.json — The semantic vocabulary defining valid terms and relationships.
• examples/*.yaml — Sample models including examples/tpcds_semantic_model.yaml and 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:

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

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 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 script provides comprehensive checking through four specialized functions.
• Schema compliance: Validates against 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 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, 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 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 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 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.

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