vault validate

Prüft einen Vault gegen die Apparat-Spezifikation und gibt einen Report aus. Pflichtfelder werden hart geprüft, Konventionsbrüche erzeugen Warnungen. Das Kommando ändert nichts — es liest nur und berichtet.

Einfachster Fall

apparat vault validate

Wenn alles sauber ist:

Vault "recherche" is clean — 42 file(s) scanned, no findings.

Wenn es etwas zu berichten gibt:

Vault "recherche" — validation findings:

content/2026-04-19--maria-beispiel--V1StGXRa.md
  ERROR  id.filename_mismatch       Field `id` "Bx7tYu3v" does not match the NanoId suffix "V1StGXRa" in the filename.
  WARN   type.case                  Type value "Person" should be lowercase.

content/2026-04-20--wcag--BbBbBbBb.md
  WARN   key.case                   Frontmatter key "birthDate" is not snake_case.

assets/stray-file.pdf
  ERROR  asset.schema               Asset filename "stray-file.pdf" does not match the schema YYYY-MM-DD--slug--nanoid.ext.

Summary: 2 errors, 2 warnings across 44 file(s) scanned, 41 clean (errors).

Jede Zeile: Severity (ERROR oder WARN), Rule-ID (maschinenlesbar, z.B. id.missing, type.case), Beschreibung.

Exit-Codes

So kann ein CI-Skript zwischen „blockend" und „kosmetisch" unterscheiden:

apparat vault validate
case $? in
  0) echo "clean" ;;
  1) echo "errors — do not ship"; exit 1 ;;
  2) echo "warnings only — proceeding, but clean up soon" ;;
esac

Maschinenlesbare Ausgabe: --json

apparat vault validate --json

Gibt ein einzelnes JSON-Objekt auf stdout aus, das den vollständigen Report enthält:

{
  "vault": {
    "name": "recherche",
    "url": "https://apparat.example.com/vaults/recherche",
    "path": "/home/max/vaults/recherche"
  },
  "summary": {
    "errors": 2,
    "warnings": 2,
    "files_scanned": 44,
    "files_clean": 41
  },
  "findings": [
    {
      "severity": "error",
      "file": "content/2026-04-19--maria-beispiel--V1StGXRa.md",
      "rule": "id.filename_mismatch",
      "message": "Field `id` \"Bx7tYu3v\" does not match the NanoId suffix \"V1StGXRa\" in the filename."
    },
    ...
  ]
}

Der Exit-Code ist derselbe wie im Textmodus. Praktisch für:

• Pre-Commit-Hook mit jq, der bestimmte Regeln hart nimmt und andere tolerant behandelt.
• Integrationen in Editoren oder Dashboards, die die Fehler strukturiert darstellen.

Vault-Auswahl

Wie bei allen Read-Kommandos: ohne --vault greift die übliche Auto-Lokalisierung (CWD-Erkennung, einziger registrierter Vault, interaktive Auswahl). Explizit:

apparat vault validate --vault=arbeit
apparat vault validate --vault=/home/max/vaults/recherche
apparat vault validate --vault=https://apparat.example.com/vaults/recherche

Was geprüft wird

Harte Fehler (Exit-Code 1)

Das sind Zustände, die verhindern, dass die Datei als reguläre Entität behandelt werden kann. Dieselben Dateien erscheinen als irregulär in vault irregular und lassen sich mit entity import in den regulären Bestand überführen.

Warnungen (Exit-Code 2)

Konventionsbrüche, die nichts kaputt machen, aber eine aufräumwürdige Drift signalisieren.

Was außerhalb des Validators liegt

Drei Klassen von Befunden werden vom Validator bewusst nicht angefasst:

• Plural-Formen bei type (persons statt person) — eine zuverlässige Singular-Erkennung braucht Wortlisten-Wissen und ist im Validator nicht vorgesehen.
• Konsistenz von Beziehungs­namen über den Vault hinweg (works_at vs. employed_at) — diese Drift fängt die Vokabular-Konsolidierung ab.
• Cross-Vault-Links. Referenzen auf andere Vaults werden nicht als verwaist markiert, solange der Ziel-Vault registriert ist — link.orphan meldet nur Ziele, die innerhalb dieses Vaults fehlen.

Abgrenzung zu anderen Kommandos

vault validate arbeitet rein lesend — der Vault wird nicht verändert, weder Inhalte noch Zeitstempel. Für gezielte Sanierung gibt es vault irregular und entity import. Der Trash hat seine eigene Listing-Ansicht (vault trash list) und wird vom Validator nicht mitgeprüft.

Verwandte Themen

• Grundbegriffe — Entität: welche Pflichtfelder eine Entität haben muss.
• Grundbegriffe — Tags und Typen: Konventionen für Typ- und Tag-Werte.