docs(spec): add ai_context to the Relationship node in spec.yaml - #350
docs(spec): add ai_context to the Relationship node in spec.yaml#350kayemkim wants to merge 2 commits into
Conversation
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 <kayemkim@gmail.com> Generated-by: Claude Code
425ea55 to
509e849
Compare
|
|
||
| # 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 |
There was a problem hiding this comment.
The schema, spec.md, the Python models, and the TPC-DS example all treat relationship ai_context as string-or-object. This PR fixes "field is missing" and introduces "field has the wrong type" (corresponding to #141).
I think it's worth changing to reflect both forms before merge, since spec.yaml handles nested shapes elsewhere (expressions, dimensions).
There was a problem hiding this comment.
Agreed. Pushed a change that documents the object form (instructions/synonyms/examples) in a comment above the field, the way primary_key and unique_keys show their alternate shapes. I kept the live value as ai_context: string to stay in line with the sibling nodes, since reworking the string-only notation across the file is what #141 tracks; or I can switch the live value to the nested form if you'd rather lead with it here.
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 <kayemkim@gmail.com> Generated-by: Claude Code
2 participants
Summary
Relationshipwas the only node where the two core-spec files disagreed on whether a field exists: the JSON schema's$defs/Relationshipcarriesai_context, and the spec.md property table lists it, but therelationships:block inspec.yamlomitted it. Every other node lists it in both files.This adds the property to the block, placed before
custom_extensionswith the comment style of the sibling nodes.spec.yamlstill parses.Related Issues
Fixes #340.
Checklist
Specification
core-spec/and follow the existing structureOntology
ontology/are consistent with spec changesConverters
converters/is updated to reflect spec or ontology changesValidation
validation/are updated if the spec changedDocumentation
docs/is updated to reflect any user-facing changesCONTRIBUTING.mdis updated if the contribution process changedExamples
examples/are added or updated for any new spec constructs or converter supportTests
pytest/ CI green)Compliance