# Complete YAML Structure for an Apache Ossie Semantic Model: Schema, Fields, and Examples > Discover the complete YAML structure for Apache Ossie semantic models. Learn about schema, fields, and examples for datasets, relationships, and more to enable cross-platform analytics. - Repository: [The Apache Software Foundation/ossie](https://github.com/apache/ossie) - Tags: schema-reference - Published: 2026-07-26 --- **An Apache Ossie semantic model is defined as a YAML document conforming to the [`core-spec/spec.yaml`](https://github.com/apache/ossie/blob/main/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`](https://github.com/apache/ossie/blob/main/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`](https://github.com/apache/ossie/blob/main/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`](https://github.com/apache/ossie/blob/main/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: ```yaml 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`](https://github.com/apache/ossie/blob/main/examples/flights.yaml) demonstrates the minimal viable structure: ```yaml 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`](https://github.com/apache/ossie/blob/main/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`](https://github.com/apache/ossie/blob/main/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`](https://github.com/apache/ossie/blob/main/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`](https://github.com/apache/ossie/blob/main/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`](https://github.com/apache/ossie/blob/main/converters/salesforce/src/main/resources/osi-salesforce-converter-config.yaml) file demonstrates how external converters reference this schema.