Machine-Readable Schemas for Ossie Validation: JSON Schema Reference

Ossie validates all semantic-model data against JSON Schema definitions shipped in the repository, using the SchemaValidator class to enforce compliance with core-spec/osi-schema.json and converter-specific schemas.

The Apache Ossie project provides machine-readable JSON Schema definitions to ensure data integrity across its semantic model ecosystem. These schemas define the canonical structure for datasets, fields, and expressions while enabling automated validation through both Java APIs and command-line interfaces. Understanding these validation schemas is essential for developers extending Ossie converters or integrating custom semantic models.

Core Ossie Schema Location

The primary machine-readable schema is osi-schema.json located in the core-spec/ directory. This file serves as the authoritative specification for the Ossie data model, describing all valid constructs including datasets, fields, and expressions.

The SchemaValidator class references this core schema through the constant:

// src/main/java/org/apache/ossie/validator/SchemaValidator.java
public static final String OSI_SCHEMA_PATH = "/schemas/osi-schema.json";

When the CLI executes ossie validate <file>, it constructs a SchemaValidator instance using this path to validate the input against the canonical model definition.

Converter-Specific Validation Schemas

Individual converters embed supplementary schemas under their src/main/resources/schemas/ directories to validate external payloads before transformation. These ensure that third-party semantic models conform to expected structures before conversion to the Ossie format.

The Salesforce converter includes a dedicated schema:

// src/main/java/org/apache/ossie/validator/SchemaValidator.java
public static final String SALESFORCE_SCHEMA_PATH = "/schemas/salesforce-semantic-model-schema.json";

This file resides at converters/salesforce/src/main/resources/schemas/salesforce-semantic-model-schema.json. Other converters—such as those for Snowflake, GoodData, and Polaris—follow the same pattern, maintaining their own validation schemas within their respective resource trees.

SchemaValidator Implementation Details

The SchemaValidator class in src/main/java/org/apache/ossie/validator/SchemaValidator.java provides the central validation mechanism. It utilizes the networknt/json-schema-validator library to load schemas from the classpath and validate JSON nodes against them.

The constructor initializes the validator by loading the specified schema:

public SchemaValidator(ObjectMapper objectMapper, String schemaPath) {
    this.schemaPath = schemaPath;
    this.schema = loadSchema();
}

The loadSchema() method retrieves the schema from the classpath, while the validate() method checks a JsonNode against the loaded schema and throws ValidationException for any violations.

Practical Validation Examples

Validating via Java API

Use the SchemaValidator directly in your application code to validate semantic models programmatically:

import org.apache.ossie.validator.SchemaValidator;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.JsonNode;
import java.io.File;

ObjectMapper mapper = new ObjectMapper();
JsonNode data = mapper.readTree(new File("my-model.json"));

// Validate against the core Ossie schema
SchemaValidator validator = new SchemaValidator(mapper, SchemaValidator.OSI_SCHEMA_PATH);
validator.validate(data);   // throws ValidationException if the model is invalid

Validating via CLI

The command-line interface provides direct access to schema validation:

# Validate a semantic-model YAML/JSON file

ossie validate path/to/model.yaml

The CLI implementation in cli/cmd/validate.go converts the input to JSON and invokes the SchemaValidator with OSI_SCHEMA_PATH, printing any validation errors to stdout.

Unit Testing with Schemas

Converter tests demonstrate schema validation in practice. The Salesforce converter test suite validates that output conforms to the core schema:

// converters/salesforce/src/test/java/org/apache/ossie/SalesforceToOsiConverterTest.java
assumeTrue(osiSchemaExists, "Ossie schema file is required but not found.");
assertDoesNotThrow(() -> validator.validate(osiRoot),
    "Output should comply with Ossie schema");

Summary

• The core schema core-spec/osi-schema.json defines the canonical Ossie semantic model and serves as the primary machine-readable specification.
• Converter-specific schemas reside in src/main/resources/schemas/ within each converter module (e.g., Salesforce, Snowflake, Polaris).
• The SchemaValidator class in src/main/java/org/apache/ossie/validator/SchemaValidator.java provides the central validation mechanism using the networknt/json-schema-validator library.
• Both Java APIs and the ossie validate CLI command rely on these schemas to enforce data correctness across all operations.

Frequently Asked Questions

What is the primary machine-readable schema for Ossie validation?

The primary schema is osi-schema.json located in the core-spec/ directory. It defines the canonical structure for Ossie semantic models, including datasets, fields, and expressions, and is referenced by the SchemaValidator class via the OSI_SCHEMA_PATH constant.

How does Ossie validate Salesforce semantic models?

The Salesforce converter uses salesforce-semantic-model-schema.json located in converters/salesforce/src/main/resources/schemas/. The SchemaValidator loads this schema via the SALESFORCE_SCHEMA_PATH constant to validate external payloads before transforming them into the Ossie format.

Can I validate Ossie models programmatically in Java?

Yes. Instantiate the SchemaValidator class from src/main/java/org/apache/ossie/validator/SchemaValidator.java with an ObjectMapper and the desired schema path (e.g., SchemaValidator.OSI_SCHEMA_PATH), then call the validate() method on your JSON node. The class uses the networknt/json-schema-validator library internally to perform validation.

Where is the CLI validation logic implemented?

The ossie validate command is implemented in cli/cmd/validate.go. It converts input files to JSON and invokes the Java-based SchemaValidator with OSI_SCHEMA_PATH to check compliance against the core schema, returning validation errors to the console.

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