Skip to content

docs: align spec yaml ai_context shape #221

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
CooperSheroy wants to merge 1 commit into
base: main
Choose a base branch
from
+39 −5
Open

docs: align spec yaml ai_context shape #221

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 39 additions & 5 deletions core-spec/spec.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,8 +53,15 @@ semantic_model:
# Optional: Human-readable description of the semantic model
description: string

# Optional: Additional context for AI tools (e.g., custom prompts, instructions)
ai_context: string
# Optional: Additional context for AI tools.
# Can be a simple string or a structured object with instructions,
# synonyms, examples, or vendor-specific keys.
ai_context:

@khush-bhatia khush-bhatia Jul 17, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This change is making the yaml version of the spec strictly only allow three subfields which are instructions, synonyms and examples.

Instead we shoudl change the type here to be {} so it can support arbitrary key values .

The issue #141 also suggests the same thing. See

# 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

@jbonofre jbonofre Jul 17, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point. Agree!

instructions: string
synonyms:
- string
examples:
- string

# Required: Collection of logical datasets (fact and dimension tables)
# See Logical Dataset section below for detailed structure
Expand Down Expand Up @@ -117,7 +124,13 @@ datasets:

# Optional: Additional context for AI tools (e.g., synonyms, common terms)
# Helps LLMs understand the business meaning and generate better queries
ai_context: string
# Can also be provided as a simple string.
ai_context:
instructions: string
synonyms:
- string
examples:
- string

# Optional: Row-level calculations for grouping, filtering, and in metric expressions
# See Fields section below for detailed structure
Expand Down Expand Up @@ -160,6 +173,15 @@ relationships:
# - [order_id, line_number] # Composite key
to_columns: [] # Array of column names

# Optional: Additional context for AI tools.
# Can be a simple string or a structured object.
ai_context:
instructions: string
synonyms:
- string
examples:
- string

# Optional: Vendor-specific attributes for extensibility
custom_extensions:
- vendor_name: string # Free-form string identifying the vendor
Expand Down Expand Up @@ -196,7 +218,13 @@ fields:

# Optional: Additional context for AI tools (e.g., synonyms, business terms)
# Helps LLMs understand the field meaning and generate better queries
ai_context: string
# Can also be provided as a simple string.
ai_context:
instructions: string
synonyms:
- string
examples:
- string

# Optional: Vendor-specific attributes for extensibility
custom_extensions:
Expand Down Expand Up @@ -225,7 +253,13 @@ metrics:

# Optional: Additional context for AI tools (e.g., synonyms, business context)
# Helps LLMs understand the metric meaning and suggest it appropriately
ai_context: string
# Can also be provided as a simple string.
ai_context:
instructions: string
synonyms:
- string
examples:
- string

# Optional: Vendor-specific attributes for extensibility
custom_extensions:
Expand Down