core-spec/spec.yaml declares `ai_context: string` but the JSON schema + canonical example use a structured object

Start by comparing the five ai_context declarations in core-spec/spec.yaml with the AIContext definition in core-spec/osi-schema.json, then check examples/tpcds_semantic_model.yaml and docs/index.md for the intended representation. Update the spec documentation so each declaration accurately describes the schema-supported forms, and confirm the canonical example remains consistent.

Summary

There is an inconsistency between the three authoritative representations of the ai_context field in OSI:

The JSON schema (which the example references via # yaml-language-server: $schema=...) is the most permissive view and is internally consistent with the canonical example. The spec.yaml is the more restrictive (and easier-to-misread) view — it's the one most readers will look at first.

Why this matters

Converters being built against the spec right now (we're working on a Databricks Metric View ↔ OSI converter as part of an OSI standardization effort with several vendors) have to pick one form. If we read spec.yaml literally, we treat ai_context as a free-text string and have to encode synonyms/instructions inside it — which loses structure and breaks round-tripping with vendors that have first-class equivalents. If we read the JSON schema, we use the object form — but then the spec.yaml file is technically misleading.

The discrepancy is the kind of thing that bites first-time implementers because spec.yaml is the most discoverable source and reads as a complete reference.

Suggested resolution

Tighten core-spec/spec.yaml so it matches the JSON schema. Concretely, at each of the five sites where ai_context: string appears, replace with something like:

# Optional: Additional context for AI tools.
# 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 — vendors may add more keys)
ai_context: {}  # see AIContext in osi-schema.json

That keeps the JSON schema as the source of truth, and the YAML spec accurately summarises it.

Happy to PR this

If maintainers agree on the direction, happy to put up a PR aligning spec.yaml to the JSON schema and bumping the dev-version commentary. Let me know which form you'd prefer for the inline doc.