2.6 KiB
D&D Spell Artifact
This contract defines the durable output of the dnd/spells extractor and
normalizer. It records source-grounded spell-casting occurrences; it is not a
spellbook, a rules lookup result, or a record of hypothetical casts.
Identity and compatibility
| Property | Value |
|---|---|
| Artifact kind | dnd/spell-list |
| Schema ID | notarius.dnd.spells |
| Schema name | notarius_dnd_spells_v1 |
| Schema version | v1 |
| Media type | application/json |
v1 is a single strict JSON object. It requires spell_casts; the array may
be empty. Each spell-cast object and source-reference object rejects unknown
fields. An incompatible shape change requires a new schema version.
Wire shape
Each spell_casts entry has these required fields:
| Field | Contract |
|---|---|
caster |
Non-empty in-world character or creature name. |
spell |
Non-empty spell name. |
source_refs |
One or more transcript evidence ranges. |
Every source reference has exactly source_id, start_unit_id, and
end_unit_id. The source ID identifies the input transcript; the unit IDs are
positive inclusive unit identifiers, and the start may not follow the end in
that source. References are evidence for the cast, not campaign-reference or
NPC-registry provenance.
{
"spell_casts": [
{
"caster": "Mira Thorn",
"spell": "Fireball",
"source_refs": [
{"source_id": "session-7", "start_unit_id": 12, "end_unit_id": 13}
]
}
]
}
Evidence and normalized form
An entry represents an actual cast or an unambiguous declared attempt. A spell mention, rules discussion, plan, or catalog match alone is not an occurrence. The configured catalog checks the name; it does not establish evidence.
When normalization is selected, recognized spell names use the effective catalog's canonical display name. Source references are put in canonical source order and exact duplicate references are removed. A later entry is collapsed only when it has the same canonical spell, the same case- and whitespace-insensitive caster identity, and the same complete valid reference sequence. Remaining entries retain their merged order.
The optional normalized NPC artifact can ground a
caster name. Its own references remain registry provenance and are never copied
into source_refs.
Related contracts
The spell-catalog overlay contract defines the configured catalog additions. The JSON output contract defines where this logical artifact is published; D&D module internals describes extraction and validation mechanics.