Complete YAML Structure for an Apache Ossie Semantic Model: Schema, Fields, and Examples

An Apache Ossie semantic model is defined as a YAML document conforming to the core-spec/spec.yaml schema, requiring only a top-level name field while supporting optional sections for datasets, relationships, metrics, and custom_extensions that enable cross-platform analytics interoperability.

Apache Ossie provides an open standard for semantic layers that bridge analytics tools and data platforms. The complete structure for defining these models is governed by the core specification file core-spec/spec.yaml, which mandates specific required fields and enumerations for dialects and data types. Understanding this YAML hierarchy—from root-level metadata to vendor-specific extensions—is critical for building portable semantic models that work across converters like Snowflake, Salesforce, and Databricks.

Top-Level semantic_model Structure

Every Ossie YAML file begins with the semantic_model key, which serves as the entry point grouping all model metadata. According to the schema in spec.yaml, this section requires minimal information but offers extensive optional configuration.

Required fields:

• name — String identifier for the semantic model

Optional fields:

• description — Human-readable documentation
• ai_context — Metadata for AI/LLM consumption
• datasets — Array of logical tables (required key but can be empty)
• relationships — Array of foreign-key links between datasets
• metrics — Array of quantitative calculations
• custom_extensions — Vendor-specific metadata attachments

Datasets and Fields

Dataset Properties

The datasets array contains logical representations of fact or dimension tables. Each dataset maps to a physical data source while defining keys, fields, and descriptive metadata.

Required fields:

• name — Identifier for the dataset
• source — Physical table or view reference (e.g., schema.table)

Optional fields:

• primary_key — Array of column names constituting the primary key
• unique_keys — Array of arrays, where each inner array represents a composite unique key
• description, ai_context — Documentation strings
• fields — Array of column or calculated field definitions
• custom_extensions — Vendor-specific extensions

Field Definitions

Fields define row-level attributes used for grouping, filtering, or metric calculations. They support multi-dialect expressions to ensure portability across SQL platforms.

Required fields:

• name — Field identifier
• expression.dialects — Array of dialect-specific implementations, each containing:
  • dialect — Expression language (must be from supported enumeration)
  • expression — The actual SQL or formula string

Optional fields:

• dimension.is_time — Boolean flag indicating temporal dimensions
• label, description, ai_context — Descriptive metadata
• datatype — Must match enumeration values: String, Integer, Decimal, Float, Boolean, Date, Time, DateTime, DateTimeTz, or Opaque
• custom_extensions — Vendor-specific data

Relationships

The relationships array defines foreign-key links between datasets, supporting many-to-one or one-to-one cardinality.

Required fields:

• name — Relationship identifier
• from — Source dataset name
• to — Target dataset name
• from_columns — Array of source column names
• to_columns — Array of target column names

Optional fields:

• custom_extensions — Vendor-specific metadata

Metrics

Metrics represent quantitative calculations defined over one or more datasets, sharing the same expression structure as fields.

Required fields:

• name — Metric identifier
• expression.dialects — Array with dialect and expression pairs (same structure as fields)

Optional fields:

• description, datatype, ai_context — Metadata
• custom_extensions — Vendor extensions

Custom Extensions

The custom_extensions field appears at every level (model, dataset, field, relationship, metric) and provides a free-form map for vendor-specific metadata without breaking core compatibility.

Required fields:

• vendor_name — String identifying the vendor
• data — Free-form content (any structure)

Supported Enumerations

The spec.yaml file defines strict enumerations that constrain certain field values:

Dialects: ANSI_SQL, SNOWFLAKE, TABLEAU, DATABRICKS, MAQL, BIGQUERY

Datatypes: String, Integer, Decimal, Float, Boolean, Date, Time, DateTime, DateTimeTz, Opaque

Vendor names: Free-form strings identifying extension vendors

Complete YAML Skeleton

Below is the fully expanded structure showing all possible fields as defined in the core specification:

semantic_model:
  - name: string                               # required

    description: string                        # optional

    ai_context: string                         # optional

    datasets:                                  # required (can be empty)

      - name: string                           # required

        source: string                         # required

        primary_key: []                         # optional array of column names

        unique_keys:                           # optional array of arrays

          - []                                   # each inner array = composite key

        description: string
        ai_context: string
        fields:                                 # optional array

          - name: string                       # required

            expression:                        # required

              dialects:
                - dialect: string               # required: e.g., "ANSI_SQL"

                  expression: string            # required: e.g., "customer_id"

            dimension:
              is_time: boolean                  # optional temporal flag

            label: string
            description: string
            datatype: string                     # must be enum value

            ai_context: string
            custom_extensions:
              - vendor_name: string
                data: string
        custom_extensions:
          - vendor_name: string
            data: string
    relationships:                             # optional array

      - name: string                           # required

        from: string                           # required

        to: string                             # required

        from_columns: []                        # required array

        to_columns: []                          # required array

        custom_extensions:
          - vendor_name: string
            data: string
    metrics:                                   # optional array

      - name: string                           # required

        expression:                            # required

          dialects:
            - dialect: string
              expression: string
        description: string
        datatype: string
        ai_context: string
        custom_extensions:
          - vendor_name: string
            data: string
    custom_extensions:
      - vendor_name: string
        data: string

Real-World Examples from the Repository

Minimal Model (flights.yaml)

The repository's examples/flights.yaml demonstrates the minimal viable structure:

semantic_model:
  - name: flights
    description: Simple model describing airline flights
    datasets:
      - name: flight
        source: flights.flight
        primary_key: [flight_id]
        fields:
          - name: flight_id
            expression:
              dialects:
                - dialect: ANSI_SQL
                  expression: flight_id
          - name: airline
            expression:
              dialects:
                - dialect: ANSI_SQL
                  expression: airline
            dimension:
              is_time: false
    relationships: []
    metrics:
      - name: total_distance
        expression:
          dialects:
            - dialect: ANSI_SQL
              expression: SUM(distance)

Full-Featured Model (tpcds_semantic_model.yaml)

For a production-scale reference, the examples/tpcds_semantic_model.yaml file demonstrates every optional section including custom extensions, AI context, multiple dialects per expression, and composite unique keys. Additionally, converters/orionbelt/tests/fixtures/tpcds_semantic_model.yaml validates the complete parsing logic for this full structure.

Summary

• The root semantic_model requires only a name field but supports comprehensive optional sections for documentation, datasets, relationships, and metrics.
• Datasets require name and source, while fields require name and expression.dialects containing specific dialect/expression pairs.
• Relationships define joins using from and to dataset references plus from_columns and to_columns arrays.
• Metrics share the same expression structure as fields, enabling multi-dialect quantitative definitions.
• Custom extensions use vendor_name and data fields at any level to support vendor-specific metadata without breaking core schema compliance.
• All expressions must use dialects from the enumeration defined in core-spec/spec.yaml, including ANSI_SQL, SNOWFLAKE, BIGQUERY, and others.

Frequently Asked Questions

What is the minimum required YAML to define a valid Ossie semantic model?

You only need a semantic_model containing a name field. While the structure supports datasets, relationships, and metrics arrays, these are optional and can be empty. However, practical models typically include at least one dataset with the required name and source fields to be useful.

How do I specify multiple SQL dialects for a single metric or field?

Use the expression.dialects array structure, where each entry contains a dialect key (such as SNOWFLAKE, BIGQUERY, or ANSI_SQL) and a corresponding expression string. This allows the same logical field or metric to translate to platform-specific SQL syntax while maintaining a single semantic definition.

Can I add vendor-specific metadata that isn't in the standard spec?

Yes, through the custom_extensions field available at the model, dataset, field, relationship, and metric levels. Each extension requires a vendor_name identifier and a data field that can contain any structure, allowing vendors to attach extra metadata without breaking compatibility with the core Ossie schema.

Where is the authoritative schema definition located?

The canonical specification resides in core-spec/spec.yaml within the Apache Ossie repository. This file defines all required and optional fields, plus enumerations for dialects and datatypes. The converters/salesforce/src/main/resources/osi-salesforce-converter-config.yaml file demonstrates how external converters reference this schema.

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