Tag schema¶

Nerthus.Core (until cutover). This page describes the frozen system that runs today and is deleted at cutover. Replaced by: not yet written.

Lookup reference for the closed, validated, Polish-only @tag schema carried on entity blocks in nerthus.entities.md and its overflow files. It covers the recognized tag set, link-value format, the temporal range grammar and its evaluation rules, the historical write rule, and the projected entity record. The surrounding model — index files, merging, the claim ledger — is the entity model.

The closed tag table¶

Every recognized tag, its kind, and the entity types that may carry it:

• multi — repeatable; evaluation returns every active entry.
• scalar — single current value; last-active-wins.
• scalar, historical — scalar whose updates close-and-append instead of replacing (see the historical write rule).
• Types — the @typ values whose blocks may carry the key; any marks a key legal on all eight.

Type scope is checked on read, never on write. The create and update routes validate a tag key against the flat schema above; neither consults the Types column, so @wymiary on the Postać Lord Tussal lands in the block like any other tag. Integrity reports it afterwards as OffTypeTag:wymiary, at Warning. An off-type @region line draws RegionMemberType too. GET /v1/api/schema (API reference) publishes the map: tagsByType keyed by the eight types, alongside universalTags for the keys every type carries. A client derives the Types column from those two fields rather than hardcoding it.

Containment has exactly one direction: the child's @lokacja. The former parent-side @zawiera convenience is retired from the closed schema; a leftover @zawiera line is an UnknownTag integrity error like any other unrecognized key.

On a Mapa, @koordynaty and @wymiary together form the rectangle the world-grid layout's overlap refusal checks — two maps claiming one tile is refused (Maps). Unplacing a map removes the @koordynaty line rather than writing an empty value. @wymiary is recorded in tiles, converted from the render's pixel size; a PNG whose sides are not an exact multiple of 32 px is refused (NotTileMultiple) rather than rounded.

On a Mapa, @lokacja is depiction, not containment. It names the place the map depicts — the importer links a map to the Lokacja carrying its base name, and the location tree and the containment graph read Lokacja blocks only, so a Mapa is never a node in the world hierarchy. One place may be depicted by several maps (floors, event copies); each map depicts exactly one place, and map-level @drzwi doors project onto locations through this link (Locations model).

@należy_do names the owner, not only a character's player. A Przedmiot — a coin holding included — names its holder this way, and that holder may be a Postać, an NPC, a Grupa, a Gracz, or a Lokacja; currency classes a holding by its holder's type (a Postać's coin is physical Margonem items, every other holder's is RP bookkeeping). A holding hangs off exactly one of @należy_do or @lokacja (Currency model).

Closed-schema validation¶

The recognized-tag set is a fixed list in code, enforced at two seams:

• On write: unknown tag ⇒ reject. A tag update naming @faction (English) or a typo @grpa is refused with a validation error (HTTP 422) before anything touches disk. There is no generic catch-all. Entity creation validates its seed tags against the same schema, additionally rejects an unknown @typ, and refuses a (name, type) pair a block already carries with 409 — a duplicate heading would merge into one entity at parse time and shadow the new block from every write path.
• On read: unknown tags are reported, not dropped. The scanner keeps every @key it finds, so a hand-edit is never silently lost; Test-NerthusEntityIntegrity reports the full finding set:

Diacritics are canonical. On disk a tag is its full Polish form: @należy_do, @ilość, @status: Usunięty, type Postać. The daemon writes diacritics only. Exactly two legacy ASCII spellings — @nalezy_do and @ilosc — are recognized on read (model build and write bodies) and normalized to the diacritic key; no other ASCII tag variant is mapped. Legacy-read normalization of values at adoption belongs to the import model.

Link values (the @url_* family)¶

The URL tags split by role and by what the link points at, so a renderer knows an image from a plain link without fetching it:

A link value is: an absolute http(s) URL, then an optional label in double quotes, then the optional (auto) marker, then an optional temporal range — in that order. The URL is the first whitespace-delimited token; the label is display text for the link. Temporal ranges work as on every tag, so retired art stays queryable:

### Rezydencja Tussal
- @typ: Lokacja
- @url_grafika: https://i.imgur.com/QVi9jT2.png "Mapa poglądowa Rezydencji Tussal"
- @url_grafika: https://i.imgur.com/1Lcwrm8.png "Mapa z ogrodem" (:2026-06)
- @url_dokument: https://docs.google.com/document/d/1AbC "Zamówienie na serwis do herbaty"

Integrity validates the shape: a value whose first token does not parse as an absolute http(s) URL is reported as InvalidUrl (Warning — legacy lore may hold odd links). A Gracz profile link needs no tag: it derives from @margonemid.

Temporal ranges¶

Any tag value may carry a parenthesized validity range after the value:

- @lokacja: Ithan (:2026-07)             # active until Jul 2026 (open start)
- @lokacja: Thuzal (2026-07:)            # active Jul 2026 onward (open-ended)
- @status:  Aktywny (2022-01:2026-06)    # active Jan 2022 – Jun 2026
- @grupa:   Gildia Teologów (2021-01:)   # joined Jan 2021, still a member

• Format: (VALID_FROM:VALID_TO). Either bound may be omitted for open-ended ranges. A value with no suffix is always-active.
• Partial dates resolve to bounds: YYYY → the full year, YYYY-MM → the full month (end bound uses the real day count), YYYY-MM-DD → an exact day.
• Range parsing is uniform — the suffix is recognized on every tag; integrity checks its validity, and the historical write rule below applies only to the ten scalar, historical tags.
• No seasons. The only temporal primitive is the dated range.

Evaluation rules¶

"Current" is a computed query, never a stored field. Given an -ActiveOn date (default: now), the daemon evaluates the history:

• Scalar tags: last-active-wins — among entries whose range covers the query date, the one with the latest start bound. Undated entries tie-break by load order: the later file wins, giving overflow files their primacy over the base index. So Opat Perrin's current Location after a 2026-07 move is Thuzal, not Ithan.
• Multi-valued tags (@alias, @grupa, @drzwi, @generyczne_nazwy, …): all-active — every entry whose range covers the query date, as a deduplicated set.

The historical write rule¶

For the ten scalar, historical tags (@lokacja, @status, @należy_do, @ilość, @koordynaty, @typ, @typ_lokacji, @outerior, @url, @region) an update never overwrites the active line. It closes that line's validity range at the write's effective month — the current month, unless the caller passes an explicit date — and appends the new value dated from that month. The block keeps the full timeline. Moving Opat Perrin to Thuzal in July 2026:

- @lokacja: Ithan (:2026-07)              # was: Ithan — closed, not erased
- @lokacja: Thuzal (2026-07:)             # appended

The rule is type-aware for one tag: on a Mapa, @koordynaty is a snapshot replaced in place, never close-and-append — the game does not slide a map sideways, so a repaint gets a new version suffix and there is no history to keep; only a Lokacja's @koordynaty stays scalar, historical. A block whose @typ the write cannot resolve falls back to the temporal rule, so history is never silently dropped.

One sanctioned variant: session transfers append their @ilość deltas as new lines dated to the session month, leaving the prior line as is — last-active-wins still resolves the newest balance, and the history keeps every step (Currency model).

A first-ever value is written undated, exactly as the importer writes it; setting the already-active value is a no-op. All other scalar tags (@pu_*, @slug, @wymiary, @plik, …) are tool-refreshed snapshots and replace in place; multi-valued tags always append a new line.

Soft-delete¶

Removal is the historical write applied to @status: the active status line is range-closed and Usunięty is appended, keeping every bullet. Semantics and consequences are in the entity model; the operator recipe is Add, edit, and retire entities.

The (auto) marker¶

A value carrying (auto) is machine-written and re-derivable; an unmarked value is operator-authored and preserved verbatim by every merge — the full authorship contract is the entity model. Grammar facts:

• The marker sits directly after the value (and its label, on a link value), before any temporal range: - @drzwi: Thuzal (auto), - @url: https://…/rezydencja_tussal.1.png (auto) (2026-07:). That order keeps a marked line range-closable.
• Matching folds the marker off — Thuzal/Rezydencja Tussal (auto) and Thuzal/Rezydencja Tussal are the same claim with different authorship.
• The daemon strips the marker from every projected value except SessionForms, which keeps claim lines raw.
• Four entity-tag families carry it today: @forma_sesyjna claims, the log-derived @drzwi doors, the checkup-refreshed Mapa @url (Locations model owns the latter two derivations), and the @first_session a harvested NPC proposal is dated with.
• The marker is not entity-only. A session's @Pliki section — the distribution target list the tool writes and rewrites whole — carries it on the section line: - @Pliki: (auto) (Sessions model). The section has no value of its own, so the marker sits where a value would. It means what it means everywhere else: the tool authored this and owns it, so an operator edit is overwritten on the next pass.

The projected entity record¶

The daemon parses the Markdown into a structured object; cmdlets return this shape with temporal fields already resolved to the requested -ActiveOn date. All values are the raw tag strings — the daemon does no numeric coercion (Quantity is "50", not an integer).

Those are universal — every record carries them. The fields below are type-scoped, present when the entity's @typ declares the tag or the block carries it (declared(type) ∪ present, the entity model):

Tag-presence fields are added to the record of any entity carrying the tag — a Gracz has a MargonemId; a Mapa has MargonemId, Url, Slug, Dimensions. The set: PuStartowe, PuSuma, PuZdobyte, PuNadmiar (the Postać PU snapshot), plus MargonemId, Url, UrlNerthus, Slug, Dimensions, Outerior, InheritsFrom, IsExterior, Floor, BaseName, Region (@region, resolved as of the query date), and the all-active link arrays ImageUrls (@url_grafika), DocumentUrls (@url_dokument), WebsiteUrls (@url_strona) — link values raw, the quoted label included.

Ref provenance fields ride the record of an @ref-carrying entity only: RefFile (the @ref value as written, repo-relative), RefForm (2.1 for a leading-list target, 2.2 for an index-shaped one), and — on a broken ref — RefBroken (true) with RefBrokenReason (the failure class from the integrity table above). An entity without @ref omits all four; the entity model owns the semantics.

Routes, envelopes, and the cmdlet ⇄ route mapping for entity reads and writes: API reference. How @alias and @generyczne_nazwy feed the resolver: Name resolution.