| # 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 |
