Summary
Relationship is the only node where the two core-spec files disagree on whether a field exists at all:
| Source |
Relationship properties |
core-spec/osi-schema.json ($defs/Relationship) |
name, from, to, from_columns, to_columns, ai_context, custom_extensions |
core-spec/spec.yaml (relationships:) |
name, from, to, from_columns, to_columns, custom_extensions |
Every other node (semantic_model, datasets, fields, metrics) carries ai_context in both files.
Why it matters
Implementations that vendor spec.yaml — rather than the JSON schema — as their prompt-facing or documentation contract never learn that a relationship can be annotated. A join whose meaning is not obvious from column names (a bridge table, a type-2 dimension, a deliberately filtered relationship) has no place to say so, even though validators accept it.
Suggested fix
Add ai_context to the relationships: block in spec.yaml, matching how it appears under datasets:.
Related
This is the third reported drift between the two files:
All three share a root cause: spec.yaml and osi-schema.json are maintained by hand with nothing checking that they agree. A CI check asserting that the property set of each node matches between the two files would catch this class of drift, and would likely surface more than these three.
Summary
Relationshipis the only node where the two core-spec files disagree on whether a field exists at all:Relationshippropertiescore-spec/osi-schema.json($defs/Relationship)name,from,to,from_columns,to_columns,ai_context,custom_extensionscore-spec/spec.yaml(relationships:)name,from,to,from_columns,to_columns,custom_extensionsEvery other node (
semantic_model,datasets,fields,metrics) carriesai_contextin both files.Why it matters
Implementations that vendor
spec.yaml— rather than the JSON schema — as their prompt-facing or documentation contract never learn that a relationship can be annotated. A join whose meaning is not obvious from column names (a bridge table, a type-2 dimension, a deliberately filtered relationship) has no place to say so, even though validators accept it.Suggested fix
Add
ai_contextto therelationships:block inspec.yaml, matching how it appears underdatasets:.Related
This is the third reported drift between the two files:
ai_context: stringbut the JSON schema + canonical example use a structured object #141 —spec.yamlsaysai_context: string; the JSON schema and the canonical example use a structured objectai_contextnorcustom_extensionsAll three share a root cause:
spec.yamlandosi-schema.jsonare maintained by hand with nothing checking that they agree. A CI check asserting that the property set of each node matches between the two files would catch this class of drift, and would likely surface more than these three.