Core spec: document root cannot carry ai_context or custom_extensions
- Dominant language
- Python
- Stars
- 2.1k
- Forks
- 267
- Avg merge
- 4d 20h
- Merged PRs (30d)
- 24
Description
### 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 `$ref`s *this* specification's `AIContext` definition:
```json
"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
- This is deliberately *compatible* with #148 / #306, which remove root keys (`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.
- #234 asks whether `ai_context` should 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.
Contributor guide
Research direction
Inspect the core document root in the schema referenced as core-spec/osi-schema.json, then review the existing AIContext and CustomExtension definitions and the ontology root precedent. Add the two optional root properties while preserving required and additionalProperties settings, and verify that existing documents and documents with multiple semantic_model entries validate.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- json
- Domain
- backend-api-design
- Issue type
- Feature
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 68/100