File Format Reference

Last reviewed: 2026-07-04

This page is the precise, on-disk contract for every file in a Plainva vault. It is written so that a tool — or another program, script or AI assistant — can read and safely edit vault files directly, without going through Plainva’s user interface. If you only use the app, you never need this page; the other guide pages cover normal use.

Everything here is plain UTF-8 text. Notes are Markdown with YAML frontmatter; databases are YAML. Nothing is proprietary and nothing is hidden.

Golden rules (read first)

1. The note is the source of truth. A .base is only a view. Property values live in the frontmatter of the individual notes — never inside the .base. To change a value, edit the note.
2. Notes stay Obsidian-native. In note frontmatter, only ever write plain scalars and lists (string, number, boolean, ISO date, YAML list). Never write a nested object or an “active/selected” flag into a note.
3. A .base uses only Obsidian’s four top-level keys (filters, formulas, properties, views). Adding any other top-level key makes Obsidian reject the whole file. All Plainva-specific data goes under nested plainva: sub-keys.
4. Preserve what you do not understand. Unknown keys must survive a read/write round-trip unchanged. Do not “clean up” keys you do not recognize.
5. Write UTF-8 without BOM, with LF line endings.

The vault at a glance

A vault is an ordinary folder. The file types you will meet:

Reserved names index.md and log.md are never regular notes; do not create ordinary content under those names.

Notes (.md)

A note is a Markdown file. An optional YAML frontmatter block (between two --- lines) at the very top holds its properties; the Markdown body follows.

---
type: Note
okf_version: "0.1"
tags: [project, active]
status: In progress
due: 2026-07-20
plainva:
  icon: "🚀"
  header_color: "#2f6f6f"
---
# My Project

A **bold** thought that links to [[Another Note]].

- [ ] First task

OKF frontmatter fields

Plainva follows OKF (Open Knowledge Format), a minimal convention. Two top-level fields:

A file without type still opens fine; it is simply “not OKF-conformant”. A missing okf_version alone is not a violation. When you create a new note, adding type (and okf_version) is good practice. See OKF for the full rationale.

Property value serialization

Each frontmatter key is one property. Write the value in the native YAML form for its type:

The “active” value of a Select/Status property is just that plain scalar. The palette of allowed options and their colors do not live in the note — they live in the governing .base (see Options and colors). This keeps the note 100 % Obsidian-native.

Quote wiki-link values ("[[X]]"). Unquoted [[X]] is a YAML flow sequence and will not parse as you intend.

The plainva: namespace in notes

Presentation-only extras are bundled under a single plainva: key so other editors can ignore them:

All three are optional. If you write none of them, omit the plainva: key entirely. Invalid values are ignored on read, never treated as an error.

Links

• Wiki link: [[Note name]] — resolved by note name across the vault. With a heading anchor: [[Note#Section]]. With display text: [[Note|shown text]].
• Markdown link: [text](relative/path.md) also works.
• Backlinks are derived automatically, including from frontmatter wiki-links (that is what makes relations show up as backlinks).

Databases (.base)

A .base file is YAML. It stores a view over notes — which notes (sources), how to show them (views), how to filter and sort, and the column schema. It stores no note values. The format is compatible with Obsidian’s Bases plugin.

Hard rules — break one and Obsidian rejects the whole file

• Only these top-level keys: filters, formulas, properties, views. Never add another top-level key. (Historically a top-level columns: key broke every file — do not reintroduce that pattern.)
• Every view needs a non-empty string name.
• A filters object carries exactly one of and / or / not at each level — never two side by side.

Plainva itself heals older files that violate the last two rules the next time it saves them, but a tool writing directly must get them right.

Property identifiers: when to use the note. prefix

This trips people up, so it is explicit:

Rule of thumb: the Obsidian-facing structural fields use note.<key> (and file.<x> for built-ins like file.name, file.folder, file.mtime); everything inside a filter formula or a plainva block uses the bare frontmatter key.

Top-level keys

• filters — which notes belong to this database (sources) and any conditions. See Filters.
• properties — the column schema, keyed by property id. Native Obsidian sub-keys like displayName (column header label) are allowed and preserved; all Plainva richness lives under properties[id].plainva.
• views — an ordered list of views. Each needs a name and a type.
• formulas — an Obsidian feature. Plainva does not author these but preserves them untouched.

The plainva: sub-key map

Everything Plainva-specific is namespaced. Three locations:

properties[<note.key>].plainva — per column:

views[i].plainva — per view:

views[0].plainva — file-wide keys, allowed only on the first view:

contextFilters is Plainva’s equivalent of Notion’s “this page” filter. Each entry is a property key; when the database is embedded in a note, its rows are scoped to that host note through that property (resolved via the link index — an owning/plain-link property matches rows pointing at the host, a computed reverse column matches what the host points at). It is deliberately not written into the native filters, so Obsidian ignores it and shows all rows; opened standalone in Plainva it is also dropped (no host) and shows all rows. Multiple entries AND-combine.

Input types

plainva.input is one of:

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

A computed reverse column has no input — it is identified solely by reverseOf.

Options and colors

Select/Status/Multi-select columns may carry a curated option list. Each option:

options:
  - value: Open          # required
    color: amber         # optional palette name (see below)
    group: Active        # optional; STATUS only — orders options into stages
  - value: Done
    color: green
    group: Closed

color is a palette name, not a CSS color. Valid names: gray, teal, blue, green, amber, coral, purple, pink. An unknown color falls back to a value-derived color.

View types

views[i].type on disk is a native Obsidian type. Plainva-only renders are written as type: table plus a plainva.render hint, so Obsidian degrades them to a plain table:

Filters

filters selects which notes are in the database and narrows them.

Source conditions decide membership:

• Folder: file.folder == "Path/To/Folder" (vault-relative; the root folder is "").
• Tag: file.hasTag("project") (no leading #).

Multiple sources are just multiple entries. No filters at all = every note in the vault.

Property conditions use bare property names and these operators:

Structure (single-rooted!): one of and / or / not, whose entries are condition strings — or one level of nested {and:[...]} / {or:[...]} group objects (Notion-style groups). Example combining a source, a condition and an OR group:

filters:
  and:
    - 'file.folder == "Projects"'
    - 'status != "Done"'
    - or:
        - 'priority == "1"'
        - 'priority == "2"'

A complete annotated .base

filters:
  and:
    - 'file.folder == "Projects"'          # source: notes in the Projects folder
properties:
  note.status:                             # column id is note.-prefixed
    displayName: Status                    # optional Obsidian column label
    plainva:
      input: status
      options:
        - value: Open
          color: amber
          group: Active
        - value: Done
          color: green
          group: Closed
views:
  - type: table                            # first view: also carries file-wide keys
    name: All projects                     # every view needs a name
    order: [file.name, note.status]        # order uses note.-prefixed ids
    plainva:
      fileIconColor: "#2f6f6f"
      newItemFolder: Projects
  - type: table                            # a board is a native table + render hint
    name: Board
    plainva:
      render: board
      groupBy: status                      # groupBy uses the BARE key

Relations (the two-sided contract)

A relation links notes to each other. This is the most error-prone thing to author by hand, because it spans three places. Get all three consistent.

1. The value lives in the source note’s frontmatter, as a wiki-link (or a list of them):

   ---
   type: Task
   project: "[[Project Alpha]]"
   ---

2. The source .base declares the relation column (relationBase = the target database; relationLimit: one for a single link):

   properties:
     note.project:
       plainva:
         input: relation
         relationBase: Projects.base
         relationLimit: one

3. The target .base may show the reverse with a computed column. Its values are not stored anywhere — they are derived from the source notes’ links:

   properties:
     note.tasks:
       plainva:
         reverseOf:
           base: Tasks.base       # the source .base (vault-relative path)
           property: project      # the BARE source property key

Worked example: Tasks ↔ Projects

Tasks.base

filters:
  and:
    - 'file.folder == "Tasks"'
properties:
  note.status:
    plainva:
      input: status
      options:
        - value: Open
          color: amber
        - value: Done
          color: green
  note.project:
    plainva:
      input: relation
      relationBase: Projects.base
      relationLimit: one
views:
  - type: table
    name: All tasks
    order: [file.name, note.status, note.project]

Projects.base

filters:
  and:
    - 'file.folder == "Projects"'
properties:
  note.tasks:
    plainva:
      reverseOf:
        base: Tasks.base
        property: project
views:
  - type: table
    name: All projects
    order: [file.name, note.tasks]

Tasks/Write proposal.md

---
type: Task
okf_version: "0.1"
status: Open
project: "[[Project Alpha]]"
---
# Write proposal

Projects/Project Alpha.md

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

Result: in Projects.base, the computed tasks column of Project Alpha lists “Write proposal”, because that task’s project links back to it. Note that Project Alpha.md has no tasks: key — the reverse side is computed, never stored.

Relation DON’Ts

• Do not write reverse values into notes. A reverseOf column is computed. Writing a tasks: key into Project Alpha.md is wrong and will not round-trip.
• Make link targets resolve. "[[Project Alpha]]" must match an existing note name, or the link shows as broken.
• Keep paths vault-relative with forward slashes and no leading ./ (Projects.base, DB/Projects.base).
• reverseOf.property is the bare source key (project), not note.project.

Self-relations and sub-items

For a relation whose target is the same database, point relationBase at that same .base. To nest children under parents in a table view, set views[i].plainva.subItemsProperty to the bare parent-relation key. Cycles are handled; with sub-items off, the rows stay flat and the values are kept.

index.md (folder table of contents)

index.md is a reserved name for a folder’s table of contents.

• Only the root index.md may carry frontmatter, and only okf_version (it marks the vault as OKF-active). A non-root index.md must be frontmatter-free — frontmatter there is a reserved-name violation.
• A Plainva-managed index.md ends with the marker <!-- plainva:index generated --> (an HTML comment, invisible in reading view). Its presence means Plainva keeps the file up to date automatically. If you hand-edit such a file, either preserve the marker (and keep the generated shape) or remove it deliberately to take over the file permanently.
• Generated listings are sections of links in the form * [Title](relative/url) - description.

If you are generating a folder overview by hand, the safe choice is to not add the marker — then Plainva will never overwrite it.

Graph views (plainva.render: "graph")

A graph view is stored like every non-native view: type: table plus the render hint. Its options live in the SAME views[i].plainva namespace:

views:
  - type: table
    name: Net
    plainva:
      render: graph
      graphEdges: [projekt]        # relation property keys drawn as edges
      graphColorBy: status         # select/status property -> node color
      graphSizeBy: prio            # number property -> node size
      graphShowExternal: true      # include relation targets outside the view

All four option keys are optional; omit them entirely when unset. Obsidian renders the same file as a plain table and must not error.

Do-not-touch and safety

• .plainva/ holds backups and internal state. Never read program logic into it or write to it.
• Unknown keys are sacred. When you rewrite a .base or a note, carry through every key you did not intend to change. Plainva itself preserves unknown .base keys via an internal raw copy; a third-party writer should do the same (parse → change only what you mean → serialize).
• Values change in the note, not the .base. To set a cell, edit the note’s frontmatter. The .base only decides which notes and columns are shown.
• Do not add top-level .base keys beyond filters / formulas / properties / views.
• Encoding: UTF-8 without BOM, LF newlines, everywhere.

See also

• Notes & Markdown — the same material from a writing-by-hand-in-the-app angle
• Databases (.base) — databases explained for everyday use
• OKF — type, okf_version, index.md and the vault conversion