(ossie) branch main updated: docs(spec): align spec.yaml ai_context with the schema at every node (#350)

[jb...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

jbonofre pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/ossie.git


The following commit(s) were added to refs/heads/main by this push:
     new 91045ce7 docs(spec): align spec.yaml ai_context with the schema at every node (#350)
91045ce7 is described below

commit 91045ce755eada25ce24058702b1ea9646023e3d
Author: Kyoungmin Kim <ka...@gmail.com>
AuthorDate: Thu Sep 10 00:54:09 2026 +0900

    docs(spec): align spec.yaml ai_context with the schema at every node (#350)
    
    * docs(spec): add ai_context to the Relationship node in spec.yaml
    
    Relationship was the only node where spec.yaml and the JSON schema
    disagreed on whether a field exists at all: the schema's
    $defs/Relationship carries ai_context (as does the spec.md table),
    but the spec.yaml relationships block omitted it. Every other node
    lists it in both files.
    
    Comment style and placement (before custom_extensions) follow the
    sibling nodes.
    
    Signed-off-by: km <ka...@gmail.com>
    Generated-by: Claude Code
    
    * docs(spec): show the object form of ai_context alongside the string form
    
    Review feedback: the schema's AIContext is string-or-object, so a bare
    "ai_context: string" traded the missing-field drift for a wrong-type
    drift. Document the object form (instructions/synonyms/examples) in a
    comment, the same way primary_key and unique_keys show their alternate
    shapes, keeping the live value in line with the sibling nodes until
    the string-only notation is reworked across the file.
    
    Signed-off-by: km <ka...@gmail.com>
    Generated-by: Claude Code
    
    * docs(spec): show ai_context as an open object on the Relationship node
    
    The schema's AIContext is string-or-object with additionalProperties,
    so neither a bare "ai_context: string" nor a closed list of three
    subfields describes it. Use the notation the spec-wide alignment
    review settled on: an empty map as the live value, with the string
    form and the optional keys in the comment above it, pointing at
    AIContext in the JSON schema.
    
    Signed-off-by: km <ka...@gmail.com>
    Generated-by: Claude Code
    
    * docs(spec): align the ai_context notation across the remaining nodes
    
    Relationship was not the only node where spec.yaml understated the
    field: semantic_model, datasets, fields and metrics all wrote
    "ai_context: string" while the schema, spec.md and the canonical
    example treat it as string-or-object with additional keys allowed.
    Leaving them as they were would have put two notations for the same
    field in one file.
    
    All five sites now use the open map, with the two accepted forms
    spelled out once where the field first appears and a pointer to
    AIContext in the JSON schema at each site.
    
    Signed-off-by: km <ka...@gmail.com>
    Generated-by: Claude Code
    
    ---------
    
    Signed-off-by: km <ka...@gmail.com>
---
 core-spec/spec.yaml | 19 +++++++++++++++----
 1 file changed, 15 insertions(+), 4 deletions(-)

diff --git a/core-spec/spec.yaml b/core-spec/spec.yaml
index 4678b004..7bcb122f 100644
--- a/core-spec/spec.yaml
+++ b/core-spec/spec.yaml
@@ -68,7 +68,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
@@ -129,7 +136,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
@@ -172,6 +179,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
@@ -225,7 +236,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:
@@ -262,7 +273,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: