79 lines
3.3 KiB
Markdown
79 lines
3.3 KiB
Markdown
# D&D Spell-Catalog Overlays
|
||
|
||
This document defines the optional JSON overlay consumed by the D&D spell
|
||
extractor. An overlay contributes campaign spell names and aliases for
|
||
recognition. It does not define spell rules, effects, levels, classes, or
|
||
transcript evidence. Bind the optional `spell_catalog` reference as described
|
||
in [Configuration](../config.md#references-and-ordered-handoffs).
|
||
|
||
## Contract Identity
|
||
|
||
| Property | Value |
|
||
| --- | --- |
|
||
| Consumer | D&D spell extraction and normalization |
|
||
| Reference slot | `spell_catalog` |
|
||
| Media type | `application/json` |
|
||
| Required schema version | `notarius.dnd.spell-catalog-overlay.v1` |
|
||
| Base catalog | Embedded D&D 5e 2014 SRD catalog |
|
||
|
||
At most one overlay document may be bound. The maintained example is
|
||
[dnd-spell-catalog.json](../../examples/dnd-spell-catalog.json).
|
||
|
||
## Wire Shape
|
||
|
||
This is a minimal valid overlay:
|
||
|
||
```json
|
||
{
|
||
"schema_version": "notarius.dnd.spell-catalog-overlay.v1",
|
||
"catalogs": [
|
||
{
|
||
"id": "campaign.example",
|
||
"ruleset": "dnd-5e-2014",
|
||
"source": {"title": "Example campaign spells"},
|
||
"spells": [{"name": "Aegis of Emberfall"}]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
| Field | Required | Meaning and constraints |
|
||
| --- | --- | --- |
|
||
| `schema_version` | Yes | Exactly `notarius.dnd.spell-catalog-overlay.v1`. |
|
||
| `catalogs` | Yes | Non-empty array of catalog objects with unique IDs. |
|
||
| `catalogs[].id` | Yes | Non-empty trimmed string. |
|
||
| `catalogs[].ruleset` | Yes | Exactly `dnd-5e-2014`. |
|
||
| `catalogs[].source.title` | Yes | Non-empty trimmed string. |
|
||
| `catalogs[].source.version` | No | String when present. |
|
||
| `catalogs[].source.url` | No | String when present. |
|
||
| `catalogs[].source.license` | No | String when present. |
|
||
| `catalogs[].spells` | Yes | Non-empty array of spell objects. |
|
||
| `catalogs[].spells[].name` | Yes | Non-empty trimmed string. |
|
||
| `catalogs[].spells[].aliases` | No | Array of non-empty trimmed strings when present. |
|
||
|
||
Unknown fields are rejected at every object level. The document must contain
|
||
one JSON value; `null` is not accepted for optional strings or aliases.
|
||
|
||
## Composition And Compatibility
|
||
|
||
Notarius starts with the embedded base catalog, then applies overlay catalogs
|
||
in ascending catalog-ID order. A new canonical spell name adds a recognition
|
||
entry. If an overlay names an existing canonical spell, it augments that spell
|
||
with aliases while retaining the established display spelling.
|
||
|
||
Repeated aliases for the same spell are accepted. A canonical-name, canonical-
|
||
to-alias, or alias-to-alias collision between different spells is rejected,
|
||
including a collision with the embedded catalog. Matching uses the catalog’s
|
||
case, whitespace, and apostrophe normalization, so authors should avoid names
|
||
or aliases that normalize to another spell.
|
||
|
||
Spell extraction receives the effective catalog as deterministic canonical-name
|
||
and alias pairs. An alias in the transcript selects its associated canonical
|
||
name; the extractor is instructed to return that canonical spelling. The
|
||
projection contains no catalog source metadata or provenance, and aliases
|
||
remain recognition context rather than transcript evidence.
|
||
|
||
The overlay is a recognition aid only. The durable spell-artifact schema and
|
||
source-evidence rules are defined by the
|
||
[D&D spell artifact contract](dnd-spell-artifacts.md).
|