Where to Find the Core Specification Document for Apache Ossie

The core specification document for Apache Ossie resides in the core-spec/ directory at the repository root, with core-spec/spec.md serving as the authoritative human-readable definition and core-spec/spec.yaml providing the machine-readable equivalent.

The Apache Ossie project defines a vendor-neutral data-semantic model that standardizes how datasets, relationships, and metrics are described across different platforms. The core specification document for Ossie establishes the canonical schema that all converters and tools in the ecosystem implement, following a hub-and-spoke architecture that eliminates point-to-point translation requirements.

Location of the Core Specification Files

The definitive source files for the Ossie specification are located in the core-spec/ folder of the apache/ossie repository. These files collectively define a vendor-neutral YAML/JSON model for datasets, relationships, fields, metrics, and optional custom_extensions.

Human-Readable Documentation

The primary reference for developers and data architects is the Markdown specification:

core-spec/spec.md contains the complete human-readable description of the Ossie model. This file details entity structures, relationship semantics, and syntax requirements, serving as the authoritative reference for constructing valid Ossie definitions.

Machine-Readable Schemas

For programmatic validation and tooling, the same specification is provided in structured formats:

core-spec/spec.yaml provides a YAML representation that mirrors the markdown documentation. Converters and validators consume this file to ensure semantic consistency across implementations.

core-spec/osi-schema.json offers a JSON Schema version that enables validation workflows with JSON-based tools and schema validation libraries.

Hub-and-Spoke Architecture Context

The core specification functions as the hub in Apache Ossie's hub-and-spoke architecture. The three files in core-spec/ define the central model that all spoke implementations—individual converters for Snowflake, dbt, GoodData, BigQuery, and other platforms—reference when translating between the hub format and vendor-specific dialects. Because every converter reads from the same core specification, tools can perform bidirectional translations without requiring direct mappings between each pair of supported systems.

Accessing the Specification Programmatically

You can load and introspect the core specification document for Ossie directly from the YAML file to support validation tasks. The following Python example demonstrates loading core-spec/spec.yaml and extracting the supported dialects enumeration:

import yaml
from pathlib import Path

# Load the specification YAML

spec_path = Path(__file__).parent.parent / "core-spec" / "spec.yaml"
with spec_path.open() as f:
    spec = yaml.safe_load(f)

# The top-level "dialects" enumeration lives under the "Enumerations" section

dialects = spec.get("Enumerations", {}).get("Dialects", [])
print("Supported dialects:", [d["Dialect"] for d in dialects])

Running this script against a cloned repository outputs:

Supported dialects: ['ANSI_SQL', 'SNOWFLAKE', 'MDX', 'TABLEAU', 'DATABRICKS', 'MAQL', 'BIGQUERY']

Versioning and Compatibility

The core specification follows SemVer versioning standards to ensure backward compatibility awareness. As implemented in apache/ossie, the current development draft is version 0.2.0.dev0, while the last stable release is 0.1.1. Downstream tools can detect compatibility changes by checking the version declared within the specification files, allowing converters to adjust their behavior when processing definitions targeting different specification versions.

Summary

• Primary location: The core specification document for Ossie is located at core-spec/spec.md in the repository root of apache/ossie.
• Machine-readable formats: YAML (spec.yaml) and JSON Schema (osi-schema.json) versions are available in the same core-spec/ directory.
• Architecture role: The spec serves as the central hub in a hub-and-spoke model, enabling vendor-neutral data definitions that converters translate to specific platforms.
• Current versions: Draft 0.2.0.dev0 (development), stable 0.1.1 (released), following SemVer for compatibility tracking.
• Programmatic access: Tools can load core-spec/spec.yaml with yaml.safe_load() to introspect supported dialects and validation rules.

Frequently Asked Questions

What is the core specification document for Ossie?

The core specification document for Ossie is the authoritative schema definition that describes how to structure datasets, relationships, fields, metrics, and extensions in a vendor-neutral format. It exists as core-spec/spec.md for human consumption and as core-spec/spec.yaml and core-spec/osi-schema.json for machine processing and validation.

How do I validate my Ossie definitions against the core spec?

You can validate definitions by loading the core-spec/spec.yaml file and using it as a reference schema within your application, or by utilizing the core-spec/osi-schema.json JSON Schema with validation libraries. Many converters in the Ossie ecosystem perform this validation automatically when processing files.

Where is the JSON Schema version of the Ossie specification?

The JSON Schema version is located at core-spec/osi-schema.json in the repository. This file provides a machine-readable validation schema that corresponds exactly to the human-readable documentation in core-spec/spec.md, enabling integration with standard JSON Schema validators.

What version of the Ossie specification is currently stable?

According to the apache/ossie source code, the last released stable version is 0.1.1, while the current development draft is 0.2.0.dev0. The specification follows SemVer, allowing tools to check version compatibility when processing Ossie definitions.

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