notarius/docs/integrations/dnd-location-artifacts.md

D&D Location Artifact

This contract defines the durable, source-grounded location registry produced by dnd/locations. It records transcript-established physical places for one source document; it is not a map, location hierarchy, campaign-wide world registry, or location description.

Identity and compatibility

Property	Value
Artifact kind	dnd/location-list
Schema ID	notarius.dnd.locations
Schema name	notarius_dnd_locations_v1
Schema version	v1
Media type	application/json
Identity policy	dnd.locations.identity.v1

v1 accepts one strict JSON object with required locations; the array may be empty. Location and source-reference objects reject unknown fields. An incompatible artifact shape or identity-policy change uses a new version or policy.

Wire shape and identity

Each location has these required fields:

Field	Contract
id	location:sha256: followed by 64 lowercase hexadecimal characters.
name	Non-empty transcript-established display name.
source_refs	One or more transcript evidence ranges that identify the place.

A source reference has exactly source_id, start_unit_id, and end_unit_id. The source ID identifies the transcript, unit IDs are positive inclusive unit identifiers, and the start may not follow the end.

{
  "locations": [
    {
      "id": "location:sha256:5c1a91f15729df0b8c257093865fdf2452b43c215375e8cf2341aa9c37bb99aa",
      "name": "Moon Gate",
      "source_refs": [
        {"source_id": "session-7", "start_unit_id": 4, "end_unit_id": 5}
      ]
    }
  ]
}

The ID is deterministic and scoped to the source document. Notarius normalizes the display name for comparison with Unicode NFKC, supported apostrophe normalization, collapsed whitespace, and case folding. It hashes compact JSON for this array, using the earliest canonical source reference as the anchor:

["dnd.locations.identity.v1", comparison_name, source_id, start_unit_id, end_unit_id]

The canonical ID is the lowercase SHA-256 digest of those bytes with the location:sha256: prefix. Equal display names are allowed when their evidence anchors differ, so a generic name does not force distinct places to collapse.

Scope, reconciliation, and evidence

Locations are physical or spatial places established by the transcript, such as planes, regions, settlements, districts, buildings, rooms, landmarks, routes, and geographic features. A generic label is permitted only when it identifies a specific place in the transcript. Notarius does not infer an unstated place or add hierarchy, coordinates, descriptions, participants, or ownership.

Normalization first applies deterministic display, evidence, and ID rules. It then may use a bounded LLM-assisted proposal to reconcile semantically duplicate records. The proposal is validated and applied conservatively; invalid or unusable proposals retain the deterministic result with retry or fallback diagnostics. The registry's source references establish registry provenance, not evidence for later artifacts.

Consumers and publication

dnd/location-occurrences requires one approved location registry through its locations reference slot. Its prompt receives an ordered source-free {id, name} projection and must not treat registry references as occurrence evidence. See the location-occurrence artifact for that contract, Configuration for binding rules, and the JSON output contract for publication.