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.

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.