From 0064c6e0bddd3539957f18b7c4c81108e69661ce Mon Sep 17 00:00:00 2001
From: Pawan Singh Kapkoti <42340841+Pawansingh3889@users.noreply.github.com>
Date: Wed, 15 Jul 2026 17:00:53 +0100
Subject: [PATCH] Make the spec's own examples validate against osi-schema.json

Four fixes, each aligning an example with a rule the schema already
states:

- The Semantic Model section example used datasets: [], violating the
  schema's minItems: 1; it now carries one minimal dataset.
- Both metric examples (total_revenue, avg_orders) wrote expression as a
  bare list, omitting the required dialects wrapper that the Expression
  Object section above them defines; they now match the schema and the
  Complete Example.
- The Complete Example presented a full document without the required
  top-level version key; it now begins with version: 0.2.0.dev0.
- spec.yaml's commented primary_key examples showed a nested list
  (- [customer_id]) while the schema defines primary_key as a flat array
  of strings; the comments now show the flat form the schema and
  spec.md's own examples use.

Verified by extracting each fixed example and running it through
validation/validate.py (schema, uniqueness, references and sqlglot
checks): all pass, including the Complete Example verbatim.

Signed-off-by: Pawan Singh Kapkoti <42340841+Pawansingh3889@users.noreply.github.com>
---
 core-spec/spec.md   | 15 ++++++++++-----
 core-spec/spec.yaml |  6 ++----
 2 files changed, 12 insertions(+), 9 deletions(-)

diff --git a/core-spec/spec.md b/core-spec/spec.md
index 8b9c10a..67a4b98 100644
--- a/core-spec/spec.md
+++ b/core-spec/spec.md
@@ -83,7 +83,9 @@ semantic_model:
     description: Sales and customer analytics model
     ai_context:
       instructions: "Use this model for sales analysis and customer insights"
-    datasets: []
+    datasets:
+      - name: orders
+        source: sales.public.orders
     relationships: []
     metrics: []
     custom_extensions:
@@ -337,8 +339,9 @@ expression:
 ```yaml
 - name: total_revenue
   expression:
-    - dialect: ANSI_SQL
-      expression: SUM(orders.amount)
+    dialects:
+      - dialect: ANSI_SQL
+        expression: SUM(orders.amount)
   description: Total revenue across all orders
   ai_context:
     synonyms:
@@ -351,8 +354,9 @@ expression:
 ```yaml
 - name: avg_orders
   expression:
-    - dialect: ANSI_SQL
-      expression: SUM(orders.amount) / COUNT(DISTINCT customers.id)
+    dialects:
+      - dialect: ANSI_SQL
+        expression: SUM(orders.amount) / COUNT(DISTINCT customers.id)
   description: Average orders
   ai_context:
     synonyms:
@@ -445,6 +449,7 @@ The following are well-known examples:
 Here's a complete semantic model example showing all components working together:
 
 ```yaml
+version: 0.2.0.dev0
 semantic_model:
   - name: ecommerce_analytics
     description: E-commerce sales and customer analytics
diff --git a/core-spec/spec.yaml b/core-spec/spec.yaml
index 7229e08..3265e79 100644
--- a/core-spec/spec.yaml
+++ b/core-spec/spec.yaml
@@ -91,11 +91,9 @@ datasets:
     # 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: [customer_id]            # Simple primary key
     #
-    # primary_key:
-    #   - [order_id, line_number] # Composite 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