# 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
# Auto-generated from ossie-schema.json ($defs.Dialect.enum).
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)
  - "BIGQUERY"              # Google BigQuery GoogleSQL
  - "SIGMA"                 # Sigma Computing spreadsheet-style formula language
  - "THOUGHTSPOT"           # ThoughtSpot formula language (not SQL)
  - "DAX"                   # Data Analysis Expressions (Power BI / Analysis Services)
  - "OSSIE_SQL_2026"        # Ossie portable SQL expression language (see expression_language.md)

# Supported logical data types for fields and metrics
# Auto-generated from ossie-schema.json ($defs.DataType.enum).
datatypes:
  - "String"                # Variable-length Unicode character data
  - "Integer"               # Exact integral number
  - "Decimal"               # Exact base-10 number
  - "Float"                 # Approximate floating-point number
  - "Boolean"               # Logical two-valued truth type
  - "Date"                  # Calendar date without time of day
  - "Time"                  # Time of day without a date or timezone
  - "DateTime"              # Date and time without a timezone or offset
  - "DateTimeTz"            # Instant identified using offset or timezone context
  - "Opaque"                # Known type outside the portable vocabulary

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


# Standalone documents contain exactly one model directly at the root.
# No semantic_model wrapper; include version alongside the model properties.
# The sections in this reference file describe separate schema components.
# Top-level semantic model definition
# 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)
# Can be either:
#   - A free-form string, or
#   - A structured object with optional keys:
#       instructions: string  # how AI should use this entity
#       synonyms:     []      # alternative names / terms
#       examples:     []      # sample questions or use cases
#     (additionalProperties: true, so vendors may add more keys)
ai_context: {}  # see AIContext in ossie-schema.json

# 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: {}  # see AIContext in ossie-schema.json

    # 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 within this model 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: Additional context for AI tools (e.g., synonyms, business context)
    # Helps LLMs understand when and why the datasets should be joined
    ai_context: {}  # see AIContext in ossie-schema.json

    # 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: Temporal-role marker
      # When true, consumers should treat this field as a time dimension
      # for time-series analysis and temporal filtering. This is a *role*
      # flag, independent of the field's data type. A field with
      # is_time: true may carry any datatype (e.g. Integer for a year
      # grain, String for a month name, Date/DateTime for a date column).
      #
      # Default: when unset, is_time defaults to true if datatype is one
      # of Date, Time, DateTime, DateTimeTz, and false otherwise. Set
      # is_time: false explicitly to opt a temporal-typed column out of
      # time-dimension treatment.
      is_time: boolean

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

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

    # Optional: Logical data type for this field
    # Must be one of the values from the 'datatypes' enum above.
    # Decimal is exact base-10 with unspecified precision and scale;
    # Float is approximate. Omit datatype when unknown or unspecified.
    # Use Opaque + custom_extensions for a known type outside the
    # portable vocabulary.
    datatype: string

    # Optional: Additional context for AI tools (e.g., synonyms, business terms)
    # Helps LLMs understand the field meaning and generate better queries
    ai_context: {}  # see AIContext in ossie-schema.json

    # 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: Logical data type for this metric
    # Must be one of the values from the 'datatypes' enum above.
    # Decimal is exact base-10 with unspecified precision and scale;
    # Float is approximate. Omit datatype when unknown or unspecified.
    # Use Opaque + custom_extensions for a known type outside the
    # portable vocabulary.
    datatype: string

    # Optional: Additional context for AI tools (e.g., synonyms, business context)
    # Helps LLMs understand the metric meaning and suggest it appropriately
    ai_context: {}  # see AIContext in ossie-schema.json

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