apache / apache/ossie

Core spec: document root cannot carry ai_context or custom_extensions

Open Beginner friendly
#322 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.