diff --git a/core-spec/spec.yaml b/core-spec/spec.yaml
index 9b21b444..c8870d9a 100644
--- a/core-spec/spec.yaml
+++ b/core-spec/spec.yaml
@@ -67,7 +67,14 @@ semantic_model:
     description: string
 
     # Optional: Additional context for AI tools (e.g., custom prompts, instructions)
-    ai_context: string
+    # 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
@@ -128,7 +135,7 @@ datasets:
 
     # Optional: Additional context for AI tools (e.g., synonyms, common terms)
     # Helps LLMs understand the business meaning and generate better queries
-    ai_context: string
+    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
@@ -171,6 +178,10 @@ relationships:
     #   - [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
@@ -224,7 +235,7 @@ fields:
 
     # Optional: Additional context for AI tools (e.g., synonyms, business terms)
     # Helps LLMs understand the field meaning and generate better queries
-    ai_context: string
+    ai_context: {}  # see AIContext in ossie-schema.json
 
     # Optional: Vendor-specific attributes for extensibility
     custom_extensions:
@@ -261,7 +272,7 @@ metrics:
 
     # Optional: Additional context for AI tools (e.g., synonyms, business context)
     # Helps LLMs understand the metric meaning and suggest it appropriately
-    ai_context: string
+    ai_context: {}  # see AIContext in ossie-schema.json
 
     # Optional: Vendor-specific attributes for extensibility
     custom_extensions: