From 509e849c6184ab5fdc6658b16620f2b7e732c46f Mon Sep 17 00:00:00 2001 From: km Date: Mon, 31 Aug 2026 17:31:04 +0900 Subject: [PATCH 1/2] 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 Generated-by: Claude Code --- core-spec/spec.yaml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/core-spec/spec.yaml b/core-spec/spec.yaml index 9b21b444..c92ed2b3 100644 --- a/core-spec/spec.yaml +++ b/core-spec/spec.yaml @@ -171,6 +171,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: string + # Optional: Vendor-specific attributes for extensibility custom_extensions: - vendor_name: string # Free-form string identifying the vendor From adeedf4b40781ac8ab3fdf2da977129aed4467d0 Mon Sep 17 00:00:00 2001 From: km Date: Wed, 2 Sep 2026 08:27:10 +0900 Subject: [PATCH 2/2] 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 Generated-by: Claude Code --- core-spec/spec.yaml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/core-spec/spec.yaml b/core-spec/spec.yaml index c92ed2b3..7edf229d 100644 --- a/core-spec/spec.yaml +++ b/core-spec/spec.yaml @@ -173,6 +173,11 @@ relationships: # Optional: Additional context for AI tools (e.g., synonyms, business context) # Helps LLMs understand when and why the datasets should be joined + # Either a free-form string, or a structured object: + # ai_context: + # instructions: string # Instructions for AI on how to use this entity + # synonyms: [] # Alternative names and terms + # examples: [] # Sample questions or use cases ai_context: string # Optional: Vendor-specific attributes for extensibility