Problem
The document root is the only node in the core spec with no ai_context and no custom_extensions.
Both keys appear on SemanticModel, Dataset, Field, Metric and Relationship. The root is closed (additionalProperties: false) with only version and semantic_model.
Because semantic_model is a list, a document can hold several models — but guidance that governs all of them has nowhere to live.
Concretely: we generate Ossie from an agent that federates several data sources, emitting one semantic_model per source. The agent's instructions apply to the whole document. Today the only way to express that is to copy them into every model's ai_context, which means:
- shared instruction is duplicated N times, and drifts;
- a consumer cannot distinguish "this was document-wide" from "this is genuinely specific to this model";
- there is no place at all for document-scoped vendor metadata.
Precedent inside Ossie
This is not a new concept for the project. An ontology document already carries ai_context on its root, and it $refs this specification's AIContext definition:
"ai_context": { "$ref": "../core-spec/osi-schema.json#/$defs/AIContext" }So the core spec already defines document-wide AI context — the core document root was simply the only root that never consumed it.
Proposal
Add two optional keys to the core document root:
ai_context — $ref: #/$defs/AIContext (the existing definition, unchanged)custom_extensions — array of the existing #/$defs/CustomExtension
Semantics: document-level context applies to every semantic model in the document; model-level ai_context adds to it and takes precedence where the two conflict.
required and additionalProperties: false are unchanged, both keys are optional, and existing documents validate exactly as before. No new $defs, no breaking change.
Notes / interaction with other work
Happy to raise this on dev@ if that is preferred before any code review. I have a branch ready if there is appetite for the change.
Problem
The document root is the only node in the core spec with no
ai_contextand nocustom_extensions.Both keys appear on
SemanticModel,Dataset,Field,MetricandRelationship. The root is closed (additionalProperties: false) with onlyversionandsemantic_model.Because
semantic_modelis a list, a document can hold several models — but guidance that governs all of them has nowhere to live.Concretely: we generate Ossie from an agent that federates several data sources, emitting one
semantic_modelper source. The agent's instructions apply to the whole document. Today the only way to express that is to copy them into every model'sai_context, which means:Precedent inside Ossie
This is not a new concept for the project. An ontology document already carries
ai_contexton its root, and it$refs this specification'sAIContextdefinition:So the core spec already defines document-wide AI context — the core document root was simply the only root that never consumed it.
Proposal
Add two optional keys to the core document root:
ai_context—$ref: #/$defs/AIContext(the existing definition, unchanged)custom_extensions— array of the existing#/$defs/CustomExtensionSemantics: document-level context applies to every semantic model in the document; model-level
ai_contextadds to it and takes precedence where the two conflict.requiredandadditionalProperties: falseare unchanged, both keys are optional, and existing documents validate exactly as before. No new$defs, no breaking change.Notes / interaction with other work
dialects,vendors) that were never in the schema. This proposal goes the other way round — it adds to the schema first and keeps the root closed.ai_contextshould exist at all. That is a broader question; this issue only asks that the existing construct be available at the one level where it is currently missing.Happy to raise this on dev@ if that is preferred before any code review. I have a branch ready if there is appetite for the change.