spec.yaml

# Licensed to the Apache Software Foundation (ASF) under one
# or more contributor license agreements.  See the NOTICE file
# distributed with this work for additional information
# regarding copyright ownership.  The ASF licenses this file
# to you under the Apache License, Version 2.0 (the
# "License"); you may not use this file except in compliance
# with the License.  You may obtain a copy of the License at
#
#   http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing,
# software distributed under the License is distributed on an
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
# KIND, either express or implied.  See the License for the
# specific language governing permissions and limitations
# under the License.

# Apache Ossie - Core Metadata Spec (YAML Schema)
# DRAFT version - in development, schema may change before 0.2.0 is released
version: 0.2.0.dev0
# 
# Goals:
# - Standardization: Establish uniform language and structure for semantic model definitions
# - Extensibility: Support domain-specific extensions while maintaining core compatibility
# - Interoperability: Enable exchange and reuse across different AI and BI applications

---
# Enumerations
# Standard enums used throughout the specification

# Supported expression language dialects
dialects:
  - "ANSI_SQL"              # Standard SQL dialect
  - "SNOWFLAKE"             # Snowflake
  - "MDX"                   # Multi-Dimensional Expressions
  - "TABLEAU"               # Tableau
  - "DATABRICKS"            # Databricks SQL
  - "MAQL"                  # GoodData MAQL (Multi-Dimensional Analytical Query Language)



# Vendor name for custom extensions (free-form string)
# Examples: "COMMON", "SNOWFLAKE", "SALESFORCE", "DBT", "DATABRICKS", "GOODDATA"
vendor_name: string

 
# Top-level semantic model definition
semantic_model:
  # Required: Unique identifier for the semantic model
  - name: string

    # Optional: Human-readable description of the semantic model
    description: string

    # Optional: Additional context for AI tools (e.g., custom prompts, instructions)
    ai_context: string

    # Required: Collection of logical datasets (fact and dimension tables)
    # See Logical Dataset section below for detailed structure
    datasets: []

    # Optional: Defines how logical datasets are connected
    # See Relationships section below for detailed structure
    relationships: []

    # Optional: 
    # These metrics can span one or more logical datasets and use relationships
    # See Metrics section below for detailed structure
    metrics: []

    # Optional: Vendor-specific attributes for extensibility
    # Allows vendors to add custom metadata without breaking core compatibility
    custom_extensions:
      - vendor_name: string  # Free-form string identifying the vendor
        data: string

---
# Logical Dataset Schema
# Represents business entities or concepts (fact and dimension tables)
# Fields are defined within the scope of a logical dataset
datasets:
  # Required: Unique identifier for the logical dataset
  - name: string

    # Required: Reference to the underlying physical table/view or query
    # Format should be either database_name.schema_name.table_name or query
    source: string
    
    # Optional: Primary key definition that uniquely identifies rows in this dataset
    # Can be a single column or a composite of multiple columns
    # This is the preferred unique identifier for this dataset and is used in relationships to determine many-to-one or one-to-one.
    # Examples:
    # primary_key:
    #   - [customer_id]           # Simple primary key
    #
    # primary_key:
    #   - [order_id, line_number] # Composite primary key
    primary_key: []  # Array of column names (single or composite)

    # Optional: Array of unique key definitions that uniquely identify rows in this dataset
    # Each unique key can be a single column or a composite of multiple columns
    # Used for determining relationship type of either many-to-one or one-to-one
    # Examples:
    # unique_keys:
    #   - [column1]
    #   - [column2, column3]
    #
    # unique_keys:
    #   - [column1, column2]      
    #   - [column3, column4]     
    unique_keys:
      - []  # Array of column names (single or composite)

    # Optional: Human-readable description of the logical dataset
    description: string

    # Optional: Additional context for AI tools (e.g., synonyms, common terms)
    # Helps LLMs understand the business meaning and generate better queries
    ai_context: string

    # Optional: Row-level calculations for grouping, filtering, and in metric expressions
    # See Fields section below for detailed structure
    fields: []

    # Optional: Vendor-specific attributes for extensibility
    custom_extensions:
      - vendor_name: string  # Free-form string identifying the vendor
        data: string

---
# Relationship Schema
# Defines how logical datasets or semantic models are connected
# Represents foreign key relationships (many-to-one or one-to-one)
relationships:
  # Required: Unique identifier for the relationship
  - name: string

    # Required: The logical dataset on the many side of the relationship
    # References a logical dataset name
    from: string

    # Required: The logical dataset on the one side of the relationship
    # References a logical dataset name
    to: string

    # Required: Array of column names in the "from" dataset (foreign key columns)
    # For simple relationships, use a single column: [column1]
    # For composite relationships, use multiple columns: [column1, column2]
    # The order of columns must correspond to the order in to_columns
    # Examples:
    #   - [customer_id]              # Simple foreign key
    #   - [order_id, line_number]    # Composite foreign key
    from_columns: []  # Array of column names

    # Required: Array of column names in the "to" dataset (primary or unique key columns)
    # Must have the same number of columns as from_columns in corresponding order
    # Examples:
    #   - [id]                       # Simple key
    #   - [order_id, line_number]    # Composite key
    to_columns: []  # Array of column names

    # Optional: Vendor-specific attributes for extensibility
    custom_extensions:
      - vendor_name: string  # Free-form string identifying the vendor
        data: string

---
# Fields Schema
# Represents row-level attributes that can be used for grouping, filtering, and metric expressions
fields:
  # Required: Unique identifier for the field within the logical dataset
  - name: string

    # Required: Expression definition with dialect support
    # Supports multiple SQL dialects for cross-platform compatibility
    # Each field can have expressions in different dialects for portability
    # Can be a simple column reference or a complex scalar expression
    expression:
      dialects:
        - dialect: string  # Must be one of the values from 'dialects' enum above, Default: "ANSI_SQL"
          expression: string  # SQL scalar expression, e.g., "customer_id", "first_name || ' ' || last_name", "UPPER(email)"

    # Optional: Dimension metadata
    # Indicates this field can be used as a dimension for grouping/filtering
    dimension:
      # Optional: Indicates if this is a time-based dimension
      # Used for time-series analysis and temporal filtering
      is_time: boolean

    # Optional: Label for categorization (e.g., "filter")
    label: string

    # Optional: Human-readable description of the field
    description: string

    # Optional: Additional context for AI tools (e.g., synonyms, business terms)
    # Helps LLMs understand the field meaning and generate better queries
    ai_context: string

     # Optional: Vendor-specific attributes for extensibility
    custom_extensions:
      - vendor_name: string  # Free-form string identifying the vendor
        data: string

---
# Metrics Schema
# Quantitative measures defined on business data
# Represents key calculations like sums, averages, ratios, etc.
metrics:
  # Required: Unique identifier for the metric
  - name: string

    # Required: Expression definition with dialect support
    # Supports multiple SQL dialects for cross-platform compatibility
    # Each metric can have expressions in different dialects for portability
    expression:
      dialects:
        - dialect: string  # Must be one of the values from 'dialects' enum above, Default: "ANSI_SQL"
          expression: string  # Full SQL expression with aggregate functions, e.g., "SUM(orders.sales)", "AVG(orders.amount)"

    # Optional: Human-readable description of the metric
    # Should explain what the metric measures and how it's used
    description: string

    # Optional: Additional context for AI tools (e.g., synonyms, business context)
    # Helps LLMs understand the metric meaning and suggest it appropriately
    ai_context: string

     # Optional: Vendor-specific attributes for extensibility
    custom_extensions:
      - vendor_name: string  # Free-form string identifying the vendor
        data: string