Dateiformat-Referenz

Stand: 2026-07-04

Diese Seite ist der genaue Formatvertrag für jede Datei in einem Plainva-Vault, so wie sie auf der Platte liegt. Sie ist so geschrieben, dass ein Werkzeug — ein anderes Programm, ein Skript oder ein KI-Assistent — Vault-Dateien direkt lesen und sicher bearbeiten kann, ohne den Umweg über Plainvas Oberfläche. Wenn Du nur die App nutzt, brauchst Du diese Seite nie; der normale Gebrauch steht in den übrigen Handbuchseiten.

Alles hier ist reiner UTF-8-Text. Notizen sind Markdown mit YAML-Frontmatter; Datenbanken sind YAML. Nichts ist proprietär, nichts versteckt.

Grundregeln (zuerst lesen)

1. Die Notiz ist die Wahrheit. Eine .base ist nur eine Ansicht. Die Werte der Eigenschaften stehen im Frontmatter der einzelnen Notizen — nie in der .base. Um einen Wert zu ändern, bearbeitest Du die Notiz.
2. Notizen bleiben Obsidian-nativ. In Notiz-Frontmatter schreibst Du ausschließlich einfache Skalare und Listen (String, Zahl, Boolean, ISO-Datum, YAML-Liste). Niemals ein verschachteltes Objekt oder ein „aktiv/ausgewählt”-Flag in eine Notiz.
3. Eine .base nutzt nur Obsidians vier Top-Level-Schlüssel (filters, formulas, properties, views). Jeder weitere Top-Level-Schlüssel bringt Obsidian dazu, die ganze Datei abzulehnen. Alles Plainva-Spezifische liegt unter verschachtelten plainva:-Unterschlüsseln.
4. Erhalte, was Du nicht verstehst. Unbekannte Schlüssel müssen einen Lese-/Schreib-Zyklus unverändert überstehen. Räume keine Schlüssel „auf”, die Du nicht kennst.
5. Schreibe UTF-8 ohne BOM, mit LF-Zeilenenden.

Der Vault auf einen Blick

Ein Vault ist ein normaler Ordner. Die Dateitypen, die Dir begegnen:

Die reservierten Namen index.md und log.md sind nie normale Notizen; lege unter diesen Namen keinen gewöhnlichen Inhalt an.

Notizen (.md)

Eine Notiz ist eine Markdown-Datei. Ein optionaler YAML-Frontmatter-Block (zwischen zwei ----Zeilen) ganz oben trägt die Eigenschaften; danach folgt der Markdown-Text.

---
type: Note
okf_version: "0.1"
tags: [projekt, aktiv]
status: In Arbeit
frist: 2026-07-20
plainva:
  icon: "🚀"
  header_color: "#2f6f6f"
---
# Mein Projekt

Ein **fetter** Gedanke mit einem Link zu [[Andere Notiz]].

- [ ] Erste Aufgabe

OKF-Frontmatter-Felder

Plainva folgt OKF (Open Knowledge Format), einer minimalen Konvention. Zwei Top-Level-Felder:

Eine Datei ohne type öffnet trotzdem einwandfrei; sie ist nur „nicht OKF-konform”. Ein fehlendes okf_version allein ist kein Verstoß. Wenn Du eine neue Notiz anlegst, ist es gute Praxis, type (und okf_version) zu ergänzen. Die vollständige Begründung steht unter OKF.

Serialisierung der Eigenschaftswerte

Jeder Frontmatter-Schlüssel ist eine Eigenschaft. Schreibe den Wert in der nativen YAML-Form seines Typs:

Der „aktive” Wert einer Auswählen-/Status-Eigenschaft ist einfach dieser Skalar. Die Menge der erlaubten Optionen und ihre Farben stehen nicht in der Notiz — sie liegen in der regierenden .base (siehe Optionen und Farben). So bleibt die Notiz zu 100 % Obsidian-nativ.

Setze Wiki-Link-Werte in Anführungszeichen ("[[X]]"). Unquotiertes [[X]] ist in YAML eine Flow-Sequenz und wird nicht wie gewünscht geparst.

Der plainva:-Namespace in Notizen

Reine Präsentations-Extras liegen gebündelt unter einem einzigen plainva:-Schlüssel, damit andere Editoren sie ignorieren können:

Alle drei sind optional. Schreibst Du keinen davon, lass den plainva:-Schlüssel ganz weg. Ungültige Werte werden beim Lesen ignoriert, nie als Fehler behandelt.

Links

• Wiki-Link: [[Notizname]] — über den Notiznamen vault-weit aufgelöst. Mit Überschriften-Anker: [[Notiz#Abschnitt]]. Mit Anzeigetext: [[Notiz|angezeigter Text]].
• Markdown-Link: [Text](relativer/pfad.md) funktioniert ebenso.
• Backlinks werden automatisch abgeleitet, auch aus Frontmatter-Wiki-Links (deshalb tauchen Relationen als Backlinks auf).

Datenbanken (.base)

Eine .base-Datei ist YAML. Sie speichert eine Ansicht über Notizen — welche Notizen (Quellen), wie sie dargestellt werden (Ansichten), wie gefiltert und sortiert wird, und das Spaltenschema. Sie speichert keine Notizwerte. Das Format ist mit Obsidians Bases-Plugin kompatibel.

Harte Regeln — bei einem Verstoß lehnt Obsidian die ganze Datei ab

• Nur diese Top-Level-Schlüssel: filters, formulas, properties, views. Niemals einen weiteren Top-Level-Schlüssel ergänzen. (Historisch machte ein Top-Level-columns: jede Datei kaputt — dieses Muster nicht wiederbeleben.)
• Jede View braucht einen nicht-leeren String-name.
• Ein filters-Objekt trägt auf jeder Ebene genau eines von and / or / not — nie zwei nebeneinander.

Plainva selbst heilt ältere Dateien, die gegen die letzten beiden Regeln verstoßen, beim nächsten Speichern; ein Werkzeug, das direkt schreibt, muss sie aber von vornherein einhalten.

Eigenschafts-Bezeichner: wann das note.-Präfix gilt

Das ist die häufigste Stolperfalle, deshalb ausdrücklich:

Faustregel: Die Obsidian-zugewandten Strukturfelder nutzen note.<key> (und file.<x> für Eingebautes wie file.name, file.folder, file.mtime); alles innerhalb einer Filter-Formel oder eines plainva-Blocks nutzt den bloßen Frontmatter-Schlüssel.

Top-Level-Schlüssel

• filters — welche Notizen zur Datenbank gehören (Quellen) und etwaige Bedingungen. Siehe Filter.
• properties — das Spaltenschema, nach Eigenschafts-ID indiziert. Native Obsidian-Unterschlüssel wie displayName (Spalten-Überschrift) sind erlaubt und werden erhalten; alle Plainva-Reichhaltigkeit liegt unter properties[id].plainva.
• views — eine geordnete Liste von Ansichten. Jede braucht name und type.
• formulas — ein Obsidian-Feature. Plainva legt sie nicht an, erhält sie aber unverändert.

Die plainva:-Unterschlüssel-Karte

Alles Plainva-Spezifische ist namespaced. Drei Orte:

properties[<note.key>].plainva — pro Spalte:

views[i].plainva — pro View:

views[0].plainva — dateiweite Schlüssel, nur auf der ersten View erlaubt:

contextFilters ist Plainvas Pendant zu Notions „this page”-Filter. Jeder Eintrag ist ein Eigenschaftsschlüssel; ist die Datenbank in eine Notiz eingebettet, werden ihre Zeilen über diese Eigenschaft auf die Wirtsnotiz gefiltert (aufgelöst über den Link-Index — eine Owning-/Wiki-Link-Eigenschaft matcht Zeilen, die auf den Wirt zeigen, eine berechnete Rückspalte das, worauf der Wirt zeigt). Er wird bewusst nicht in die nativen filters geschrieben, sodass Obsidian ihn ignoriert und alle Zeilen zeigt; alleine in Plainva geöffnet entfällt er ebenfalls (kein Wirt) und zeigt alle Zeilen. Mehrere Einträge werden UND-verknüpft.

Input-Typen

plainva.input ist einer von:

text  number  checkbox  date  datetime
select  status  multiselect
list  tags  url  email  phone
relation

Eine berechnete Rück-Spalte hat kein input — sie wird allein durch reverseOf gekennzeichnet.

Optionen und Farben

Auswählen-/Status-/Mehrfachauswahl-Spalten können eine kuratierte Optionsliste tragen. Jede Option:

options:
  - value: Offen         # Pflicht
    color: amber         # optionaler Paletten-Name (siehe unten)
    group: Aktiv         # optional; NUR Status — ordnet Optionen in Stufen
  - value: Erledigt
    color: green
    group: Abgeschlossen

color ist ein Paletten-Name, keine CSS-Farbe. Gültige Namen: gray, teal, blue, green, amber, coral, purple, pink. Eine unbekannte Farbe fällt auf eine aus dem Wert abgeleitete Farbe zurück.

Ansichtstypen

views[i].type ist auf der Platte ein nativer Obsidian-Typ. Plainva-only-Ansichten werden als type: table plus plainva.render-Hinweis geschrieben, sodass Obsidian sie zur einfachen Tabelle degradiert:

Filter

filters wählt aus, welche Notizen in der Datenbank sind, und grenzt sie ein.

Quellen-Bedingungen entscheiden über die Mitgliedschaft:

• Ordner: file.folder == "Pfad/Zum/Ordner" (vault-relativ; der Wurzelordner ist "").
• Tag: file.hasTag("projekt") (ohne führendes #).

Mehrere Quellen sind einfach mehrere Einträge. Gar kein filters = jede Notiz im Vault.

Eigenschafts-Bedingungen nutzen bloße Eigenschaftsnamen und diese Operatoren:

Struktur (einwurzelig!): eines von and / or / not, dessen Einträge Bedingungs-Strings sind — oder eine Ebene verschachtelter {and:[...]} / {or:[...]}-Gruppenobjekte (Notion-artige Gruppen). Beispiel mit Quelle, Bedingung und ODER-Gruppe:

filters:
  and:
    - 'file.folder == "Projekte"'
    - 'status != "Erledigt"'
    - or:
        - 'prio == "1"'
        - 'prio == "2"'

Eine vollständige, kommentierte .base

filters:
  and:
    - 'file.folder == "Projekte"'          # Quelle: Notizen im Ordner Projekte
properties:
  note.status:                             # Spalten-ID ist note.-präfigiert
    displayName: Status                    # optionale Obsidian-Spaltenbeschriftung
    plainva:
      input: status
      options:
        - value: Offen
          color: amber
          group: Aktiv
        - value: Erledigt
          color: green
          group: Abgeschlossen
views:
  - type: table                            # erste View: trägt auch die dateiweiten Schlüssel
    name: Alle Projekte                    # jede View braucht einen Namen
    order: [file.name, note.status]        # order nutzt note.-präfigierte IDs
    plainva:
      fileIconColor: "#2f6f6f"
      newItemFolder: Projekte
  - type: table                            # ein Board ist eine native Tabelle + Render-Hinweis
    name: Board
    plainva:
      render: board
      groupBy: status                      # groupBy nutzt den BAREN Schlüssel

Relationen (der zweiseitige Vertrag)

Eine Relation verknüpft Notizen miteinander. Das ist das Fehleranfälligste beim Schreiben von Hand, weil es sich über drei Stellen erstreckt. Halte alle drei konsistent.

1. Der Wert steht im Frontmatter der Quell-Notiz, als Wiki-Link (oder eine Liste davon):

   ---
   type: Task
   projekt: "[[Projekt Alpha]]"
   ---

2. Die Quell-.base deklariert die Relations-Spalte (relationBase = die Ziel-Datenbank; relationLimit: one für einen einzelnen Link):

   properties:
     note.projekt:
       plainva:
         input: relation
         relationBase: Projekte.base
         relationLimit: one

3. Die Ziel-.base kann die Rückrichtung mit einer berechneten Spalte zeigen. Ihre Werte werden nirgends gespeichert — sie werden aus den Links der Quell-Notizen abgeleitet:

   properties:
     note.aufgaben:
       plainva:
         reverseOf:
           base: Aufgaben.base    # die Quell-.base (vault-relativer Pfad)
           property: projekt      # der BARE Quell-Eigenschaftsschlüssel

Durchgespieltes Beispiel: Aufgaben ↔ Projekte

Aufgaben.base

filters:
  and:
    - 'file.folder == "Aufgaben"'
properties:
  note.status:
    plainva:
      input: status
      options:
        - value: Offen
          color: amber
        - value: Erledigt
          color: green
  note.projekt:
    plainva:
      input: relation
      relationBase: Projekte.base
      relationLimit: one
views:
  - type: table
    name: Alle Aufgaben
    order: [file.name, note.status, note.projekt]

Projekte.base

filters:
  and:
    - 'file.folder == "Projekte"'
properties:
  note.aufgaben:
    plainva:
      reverseOf:
        base: Aufgaben.base
        property: projekt
views:
  - type: table
    name: Alle Projekte
    order: [file.name, note.aufgaben]

Aufgaben/Angebot schreiben.md

---
type: Task
okf_version: "0.1"
status: Offen
projekt: "[[Projekt Alpha]]"
---
# Angebot schreiben

Projekte/Projekt Alpha.md

---
type: Project
okf_version: "0.1"
---
# Projekt Alpha

Ergebnis: In Projekte.base listet die berechnete aufgaben-Spalte von Projekt Alpha „Angebot schreiben”, weil das projekt-Feld dieser Aufgabe darauf zurückverweist. Beachte: Projekt Alpha.md hat kein aufgaben:-Feld — die Rückseite wird berechnet, nie gespeichert.

Relations-DON’Ts

• Schreibe keine Rückwerte in Notizen. Eine reverseOf-Spalte ist berechnet. Ein aufgaben:-Feld in Projekt Alpha.md zu schreiben ist falsch und überlebt keinen Roundtrip.
• Sorge dafür, dass Link-Ziele auflösen. "[[Projekt Alpha]]" muss zu einem existierenden Notiznamen passen, sonst erscheint der Link als defekt.
• Halte Pfade vault-relativ mit Schrägstrichen und ohne führendes ./ (Projekte.base, DB/Projekte.base).
• reverseOf.property ist der bare Quell-Schlüssel (projekt), nicht note.projekt.

Self-Relationen und Unterelemente

Für eine Relation, deren Ziel dieselbe Datenbank ist, zeigt relationBase auf genau diese .base. Um Kinder unter Eltern in einer Tabellenansicht zu verschachteln, setze views[i].plainva.subItemsProperty auf den baren Eltern-Relations-Schlüssel. Zyklen werden abgefangen; ohne Unterelemente bleiben die Zeilen flach und die Werte erhalten.

index.md (Inhaltsverzeichnis eines Ordners)

index.md ist ein reservierter Name für das Inhaltsverzeichnis eines Ordners.

• Nur die Wurzel-index.md darf Frontmatter tragen, und dort nur okf_version (es kennzeichnet den Vault als OKF-aktiv). Eine index.md außerhalb der Wurzel muss frontmatter-frei sein — Frontmatter dort ist ein Reservname-Verstoß.
• Eine Plainva-verwaltete index.md endet mit dem Marker <!-- plainva:index generated --> (ein HTML-Kommentar, in der Leseansicht unsichtbar). Sein Vorhandensein bedeutet, dass Plainva die Datei automatisch aktuell hält. Bearbeitest Du so eine Datei von Hand, dann erhalte entweder den Marker (und die generierte Form) oder entferne ihn bewusst, um die Datei dauerhaft zu übernehmen.
• Generierte Listings sind Abschnitte aus Links in der Form * [Titel](relativer/url) - beschreibung.

Erzeugst Du eine Ordnerübersicht von Hand, ist die sichere Wahl, den Marker nicht zu setzen — dann überschreibt Plainva sie nie.

Nicht-anfassen und Sicherheit

• .plainva/ enthält Backups und internen Zustand. Niemals daraus Programmlogik lesen oder hineinschreiben.
• Unbekannte Schlüssel sind heilig. Wenn Du eine .base oder eine Notiz neu schreibst, trage jeden Schlüssel unverändert mit, den Du nicht ändern wolltest. Plainva selbst erhält unbekannte .base-Schlüssel über eine interne Rohkopie; ein Fremd-Schreiber sollte dasselbe tun (parsen → nur das Gemeinte ändern → serialisieren).
• Werte ändern sich in der Notiz, nicht in der .base. Um eine Zelle zu setzen, bearbeite das Frontmatter der Notiz. Die .base entscheidet nur, welche Notizen und Spalten gezeigt werden.
• Ergänze keine Top-Level-.base-Schlüssel über filters / formulas / properties / views hinaus.
• Encoding: UTF-8 ohne BOM, LF-Zeilenenden, überall.

Graph-Ansichten (plainva.render: "graph")

Eine Graph-Ansicht wird wie jede nicht-native Ansicht gespeichert: type: table plus Render-Hinweis. Ihre Optionen liegen im SELBEN views[i].plainva-Namensraum:

views:
  - type: table
    name: Netz
    plainva:
      render: graph
      graphEdges: [projekt]        # Relations-Eigenschaften, die als Kanten erscheinen
      graphColorBy: status         # Auswahl-/Status-Eigenschaft -> Knotenfarbe
      graphSizeBy: prio            # Zahl-Eigenschaft -> Knotengröße
      graphShowExternal: true      # Relationsziele außerhalb der Ansicht einblenden

Alle vier Options-Schlüssel sind optional; ungesetzte werden komplett weggelassen. Obsidian rendert dieselbe Datei als einfache Tabelle und darf keinen Fehler zeigen.

Siehe auch

• Notizen & Markdown — dasselbe Material aus dem Blickwinkel „von Hand in der App schreiben”
• Datenbanken (.base) — Datenbanken für den Alltag erklärt
• OKF — type, okf_version, index.md und die Vault-Konvertierung