First version of the OSI spec

core-spec/spec.yaml

@@ -0,0 +1,222 @@
+# OSI - Core Metadata Spec (YAML Schema)
+# Version: 1.0
+# 
+# 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 SQL and expression language dialects
+dialects:
+  - "ANSI_SQL"              # Standard SQL dialect
+  - "SNOWFLAKE_SQL"         # Snowflake
+  - "MDX"                   # Multi-Dimensional Expressions
+  - "TABLEAU"               # Tableau
+  - "BIGQUERY_SQL"          # Google BigQuery
+  - "REDSHIFT_SQL"          # Amazon Redshift
+  - "DATABRICKS_SQL"        # Databricks
+  - "POSTGRESQL"            # PostgreSQL
+  - "MYSQL"                 # MySQL
+
+
+
+# Supported vendors for custom extensions
+vendors:
+  - "COMMON"
+  - "SNOWFLAKE"
+  - "SALESFORCE"
+  - "DBT"
+
+
+# Standard aggregation types for structured metrics
+aggregation_types:
+  # Basic aggregations
+  - "SUM"
+  - "AVG"
+  - "COUNT"
+  - "COUNT_DISTINCT"
+  - "MIN"
+  - "MAX"
+
+
+# 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  # Must be one of the values from 'vendors' enum above
+        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:
+    #   - [customer_id]           # Simple 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:
+    #   - [column1]              # Simple key on one column
+    #   - [column2, column3]     # Composite key on two columns
+    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  # Must be one of the values from 'vendors' enum above
+        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  # Must be one of the values from 'vendors' enum above
+        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: SQL expression that defines how to compute this field
+    # Can be a simple column reference or a complex scalar expression
+    expression: string
+
+    # 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  # Must be one of the values from 'vendors' enum above
+        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 within the logical dataset
+  - name: string
+
+    # Required: Expression definition with dialect support
+    # Supports multiple SQL dialects for cross-platform compatibility
+    expression:
+      - dialect: string  # Must be one of the values from 'dialects' enum above, Default: "ANSI_SQL"
+      # Must be one of the following two options
+      # Option 1: Full expression with aggregate function 
+        expression: string  # e.g., "SUM(sales)", "AVG(revenue)"
+
+      # Option 2: Structured  
+        aggregation_type: string  # Must be one of the values from 'aggregation_types' enum above
+        input_expr: string  # Must be a scalar expressions e.g., "sales", "revenue", "quantity"
+
+    # 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  # Must be one of the values from 'vendors' enum above
+        data: string