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

[epeyman]

Summary

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

Source	Says ai_context is	Permalink
core-spec/spec.yaml	a string (literally ai_context: string at every level — semantic_model, datasets, fields, metrics)	spec.yaml#L39, #L102, #L181, #L210
core-spec/osi-schema.json ($defs/AIContext)	oneOf: [string, object{instructions, synonyms, examples, …, additionalProperties: true}]	osi-schema.json
examples/tpcds_semantic_model.yaml (canonical example)	a structured object with instructions (on semantic_model) and synonyms (on datasets/fields/metrics) — never a plain string	tpcds_semantic_model.yaml
docs/index.md	"Optional annotations at every level … including instructions, synonyms, and example queries"	docs/index.md

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.

[khush-bhatia]

Hey @epeyman Thanks, agreed on changing the spec.yaml to align with the json schema.

[onkardahale]

Thanks for laying it out so clearly!
@epeyman since you mentioned you’d be happy to PR this, do you still want to take it? If not, I’m happy to open a PR!

[utkarshparekh]

Hi @epeyman, @onkardahale, and @khush-bhatia

I’m interested in preparing a focused PR for this issue, but I’d like to confirm ownership and scope before starting.

First, are either @epeyman or @onkardahale currently working on a PR? I don’t want to duplicate anyone’s work.

I compared the current representations and understand the intended behavior as follows:

• core-spec/osi-schema.json defines AIContext as either a free-form string or a structured object.
• The structured object supports instructions, synonyms, and examples, while allowing additional properties.
• core-spec/spec.md and the Python models already represent this union correctly.
• This applies to five locations: semantic models, datasets, relationships, fields, and metrics.
• core-spec/spec.yaml currently says ai_context: string in four locations and omits ai_context from the relationship section.

If the issue is available, my proposed minimal scope is:

1. Update the four existing ai_context entries in core-spec/spec.yaml to describe both supported forms.
2. Add the missing optional ai_context entry to the relationship section.
3. Leave osi-schema.json, spec.md, Python models, examples, and converters unchanged because their behavior is already correct.
4. Keep the version at 0.2.0.dev0, since this clarifies existing behavior rather than changing the specification.
5. Validate that spec.yaml still parses and that both string and structured forms continue to validate against osi-schema.json.

For the placeholder notation, I suggest using:

# Optional: Additional context for AI tools.
# Either a free-form string or a structured object with optional
# instructions, synonyms, examples, and additional properties.
ai_context: string/object  # See AIContext in osi-schema.json