docs(spec): align spec.yaml ai_context with the schema at every node

[kayemkim]

Summary

spec.yaml understated ai_context in two different ways. On Relationship the field was missing outright, even though the JSON schema's $defs/Relationship carries it and the spec.md property table lists it. On the other four nodes it was written as ai_context: string, while the schema defines AIContext as string-or-object with additionalProperties: true, spec.md documents it as string/object at all five nodes, and the canonical TPC-DS example uses the object form.

The notation is the one suggested in #141 and asked for during the review of #221: an open map as the value, the two accepted forms spelled out once where the field first appears, and a pointer to AIContext in the JSON schema at each site. Nothing normative changes. The JSON schema is untouched and already accepts both forms, as do the Python models.

The first commit adds the field to Relationship, the second aligns the remaining four nodes. spec.yaml still parses.

Related Issues

Fixes #340. Also covers #141, which asked for exactly this alignment; #221 proposed it as well but has had changes requested since July without an update.

[jbonofre]

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).

[kayemkim]

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.

[kayemkim]

I went back through the history on this, and the notation question already has an answer in the tracker. #141 proposes this exact form in its suggested resolution, khush-bhatia asked for it on #221 (spelling out instructions, synonyms and examples as a fixed set understates AIContext, which sets additionalProperties: true), and you agreed with it there. #221 has had changes requested since July 17 without being picked back up, so instead of asking you to choose between the two options I raised earlier, I have applied that form here:

# Optional: Additional context for AI tools (e.g., custom prompts, instructions)
# 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

The first commit puts the Relationship node in that form. The second extends it to semantic_model, datasets, fields and metrics, which all still read ai_context: string: fixing only Relationship would leave two notations for the same field in one file, and spec.md already documents string/object at all five nodes. That covers #141 as well. If you would rather keep this PR to the single node it started with, dropping the second commit does that.

spec.yaml still parses, and $defs for all five nodes reference AIContext.

[jbonofre]

Good one! Thanks!