Entität

Eine Entität ist die kleinste eigenständige Informationseinheit in Apparat. Sie steht in einer einzelnen Markdown-Datei.

Aufbau

Eine Entität besteht aus zwei Teilen — dem Frontmatter und dem Fließtext:

---
id: V1StGXRa
type: person
created: 2026-04-19
language: de
updated: '2026-04-19T14:22:10+02:00'
title: Maria Beispiel
tags:
  - kollegin
  - wcag
---

# Maria Beispiel

Maria arbeitet seit 2022 als Accessibility-Spezialistin bei einer Agentur
in Berlin. Kennengelernt beim WCAG-Workshop im März.

Der Frontmatter (zwischen den beiden ----Zeilen) trägt die strukturierten Daten.
Der Fließtext (alles darunter) ist dein normaler Notiz-Inhalt, in ganz gewöhnlichem Markdown.

Pflichtfelder

Jede Entität braucht vier Felder:

id — ein acht Zeichen langer, zufällig erzeugter Identifikator (eine sogenannte NanoID). Wird beim Anlegen automatisch vergeben und ändert sich nie. Das ist die stabile Identität der Entität, unabhängig davon, wie du die Datei später umbenennst.
type — was diese Entität ist. Frei wählbar, aber englisch, kleingeschrieben und im Singular — person, project, concept, book, interview und so weiter. Eine Entität kann mehreren Typen gleichzeitig angehören: type: [document, concept].
created — das Datum, an dem du die Entität angelegt hast, im Format YYYY-MM-DD.
language — die Hauptsprache des Dokuments als BCP-47-Subset: de, en, fr (ISO-639-1-Code), optional mit Region de-DE, en-GB, pt-BR. Regex-Definition: ^[a-z]{2,3}(-[A-Z]{2})?$. Gemeint ist die Sprache, in der der Fließtext überwiegend verfasst ist — mischsprachige Dokumente geben die dominante Sprache an. Beim Anlegen schlägt Apparat den konfigurierten Default (APPARAT_DEFAULT_LANGUAGE, per Vault-Installation gesetzt) als Vorauswahl vor; du kannst ihn jederzeit überstimmen.

Optionale Standard-Felder

title — Anzeigeform. Wenn nicht gesetzt, nimmt Apparat die erste H1-Überschrift im Fließtext.
tags — Liste freier Schlagworte.
updated — wird vom System automatisch bei jeder Änderung gesetzt, du selbst solltest das Feld nicht anfassen.
deleted — markiert eine soft-gelöschte Entität (ISO-Datum). Gesetzt vom Backend, wenn du entity delete aufrufst; gleichzeitig wandert die Datei von content/ nach .apparat/trash/. Entitäten mit deleted erscheinen nicht in Listen, Suchen oder im Graph. Details siehe entity delete.
representations — Verweise auf zugehörige Assets (Fotos, Audio-Aufnahmen, PDFs).
external — Verweise auf externe URLs (z.B. ein YouTube-Video als Quelle).

Eigene Felder

Alles andere ist dir überlassen. Du kannst jederzeit weitere Felder hinzufügen:

---
id: V1StGXRa
type: person
created: 2026-04-19
language: de
title: Maria Beispiel
birthday: 1982-03-15
residence: Berlin
languages: [de, en, fr]
---

Apparat liest diese Felder ein, legt sie am Graph-Knoten ab und macht sie für Suchen verfügbar. Ein festes Schema gibt es nicht.

Felder dürfen verschachteln (eine Map, darin wieder Schlüssel/Werte), aber nur bis zu einer maximalen Tiefe von drei Ebenen — ein einfacher Wert, eine Map, eine Map in der Map. Tiefer wird bewusst nicht unterstützt: so tief verschachtelte Metadaten gehören eher in den Fließtext. Der Grenzwert lässt sich pro Installation über APPARAT_FRONTMATTER_MAX_DEPTH anpassen; der Editor verweigert das Speichern, wenn eine Notiz tiefer würde.

Beziehungsfelder

Verbindungen zu anderen Entitäten werden als verbhafte Frontmatter-Felder ausgedrückt:

works_at: "[Organisation XY](./2023-05-01--organisation-xy--Qw9pLm2n.md)"
knows:
  - "[Max Mustermann](./2024-02-14--max-mustermann--Bx7tYu3v.md)"
  - "[Anna Schmidt](./2025-08-09--anna-schmidt--Fg6hJk4l.md)"

Namen der Beziehungen sind englisch, Aktiv, Verb-haft (works_at, nicht employer).
Mehrwort-Beziehungen mit Unterstrich (knows_personally, nicht knowsPersonally).
Der Wert ist ein ganz normaler Markdown-Link auf die Ziel-Datei.

Eine Beziehung kann zusätzliche, frei wählbare Felder tragen — wann sie begann, in welcher Rolle, mit welchen Konditionen. Dafür wird der Markdown-Link durch eine YAML-Map mit target: plus den Zusatzfeldern ersetzt:

works_at:
  target: Qw9pLm2n
  since: 2019
  role: lead

Die Zusatzfelder fließen sowohl in die Antworten des Chats als auch in die semantische Suche ein — eine Frage wie „wer arbeitet seit 2019 bei Tollwerk" findet so direkt einen Treffer.

Beziehungen sind gerichtet — du schreibst sie nur einmal, bei der Entität von der aus sie ausgehen. Apparat berechnet die umgekehrte Richtung automatisch, sobald die Graph-Schicht aktiv ist.

Dateiname

Eine Entität landet unter content/ im Vault, mit einem sprechenden Dateinamen nach dem Schema:

YYYY-MM-DD--slug--nanoid.md

Zum Beispiel: 2026-04-19--maria-beispiel--V1StGXRa.md

Das Datum und der Slug sind rein kosmetisch — Apparat identifiziert Entitäten ausschließlich über die NanoID am Ende. Du darfst den Slug also umbenennen, ohne dass irgendein Link kaputtgeht. Die NanoID bleibt gleich, und Apparat findet die Datei weiter.

Was passiert, wenn eine Datei kaputt ist?

Wenn eine Markdown-Datei im content/-Verzeichnis nicht dem Schema entspricht — kein NanoID-Suffix, defektes Frontmatter, fehlendes Pflichtfeld — gilt sie als irregulär. Sie ist nicht über Links erreichbar, erscheint nicht im Graph und taucht nicht in der Suche auf, der Inhalt auf der Festplatte bleibt aber unverändert liegen.

vault irregular listet alle irregulären Dateien im Vault mit einem kurzen Befund pro Eintrag. entity import überführt eine irreguläre Datei — oder eine externe Markdown-Datei, die du neu aufnehmen willst — in den regulären Bestand: Pflichtfelder werden interaktiv abgefragt, NanoID vergeben (oder erhalten, falls bereits im Dateinamen), Dateiname ans Schema angepasst. vault validate meldet dieselben Zustände zusätzlich als Hard-Rule-Findings, wenn du sie im Rahmen eines kompletten Konventions-Checks sehen willst.