# Medium overlays

Core types are medium-agnostic. A Character is a Character in a novel, a screenplay, a game
and a comic, and the core schema says only the things all four agree on.

Everything one medium needs and the others do not lives under `extensions`, namespaced:

```json
{
  "id": "scene:the-bell-does-not-ring",
  "specType": "scene",
  "specVersion": "0.1.0",
  "name": "The bell does not ring",
  "purpose": "Establish the count, the wall, and that she is alone on it.",
  "extensions": {
    "novel": { "chapterFunction": "turn", "viewpointDistance": "close" }
  }
}
```

## Two verdicts, not one

A known overlay is validated against its schema. **Its failures never invalidate the core
object.**

That separation is the contract. An overlay-unaware reader has to understand the object
without the overlay, so a `novel` block with a bad `viewpointDistance` cannot be allowed to
invalidate a character that every other tool reads perfectly well. The overlay is wrong;
the character is not.

```js
const r = validateObject(character)
r.valid         // the core verdict
r.overlayValid  // the overlay verdict, independent of it
r.overlayErrors // what failed, if anything
```

Overlay errors appear in the combined `errors` list at `warning` severity, so a caller that
only rejects on `severity === "error"` keeps working unchanged.

## Known namespaces

| Namespace | Medium | Schema |
| --- | --- | --- |
| `novel` | Prose fiction, single or serial | [`overlays/novel.json`](../schema/v0/overlays/novel.json) |
| `screen` | Film and television | [`overlays/screen.json`](../schema/v0/overlays/screen.json) |
| `game` | Interactive and systemic narrative | [`overlays/game.json`](../schema/v0/overlays/game.json) |
| `graphic` | Comics and graphic novels | [`overlays/graphic.json`](../schema/v0/overlays/graphic.json) |

## Anything else is opaque

A namespace not in that table is **not validated at all**. It round-trips untouched and the
core validator does not read it.

This is deliberate. Overlays are where experiments land, and demanding a published schema
before anyone can try something is how a spec stops being useful for the thing it was built
for. Put your tool's data under your own namespace and it will survive every read and write
without anyone having to agree with you first.

## The one hard rule

**An overlay may never shadow a core field name.** `extensions.novel.name` is an error, not
a warning — an overlay-unaware reader would still see the core `name`, so two readers would
disagree about the same document, and neither could tell.

## Which side is a field on?

If an overlay-unaware reader would be confused without it, it is core. If they would simply
not miss it, it is an overlay. See [CONTRIBUTING.md](../CONTRIBUTING.md) — that question is
the whole of the review.