notarius/docs/integrations/dnd-spell-catalog-overlays.md

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.

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.

Wire Shape

This is a minimal valid overlay:

{
  "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.