Obsidian Front Matter: Property Types and Examples

November 11, 2026 · 11 min read

Obsidian Front Matter: Properties, Types and Examples

Obsidian front matter is the YAML block between two --- lines at the top of a note, and Obsidian calls its contents properties. Each property has a name, a value and one of seven types. This guide shows the YAML each type writes, the reserved keys that changed in Obsidian 1.9, and how to query properties.

What Is Obsidian Front Matter? Frontmatter vs Properties

Front matter is the raw text: a YAML block at the very top of the file, opened and closed by a line of three dashes. Properties is Obsidian's name for the same data, and for the panel that edits it. When you change a value in the panel, Obsidian updates the YAML underneath, so you're looking at one set of data in two ways.

You choose how the block appears under Settings → Editor → Properties in document. There are three options:

  • Visible (the default) shows the properties panel at the top of the note.
  • Hidden removes it from the note, though the Properties view in the sidebar still shows it.
  • Source shows the plain YAML text instead of the panel.

Obsidian YAML front matter follows the normal YAML rules for colons, quotes and indentation. Those rules aren't specific to Obsidian, so our guide to Markdown frontmatter covers them. This post stays inside Obsidian.

How to Add Front Matter in Obsidian

The Obsidian Properties help page lists four ways to start a properties block:

  1. Run Add file property from the command palette.
  2. Press Cmd+; on macOS or Ctrl+; on Windows and Linux.
  3. Open the More options menu (the three dots, or right-click the tab) and choose Add file property.
  4. Type --- at the very beginning of the file.

Each method adds a row with two inputs: the property name and its value. With a property focused, the down arrow or Tab moves you to the next one. If you'd rather type the YAML yourself, set the display mode to Source. It's also the quickest way to see exactly what Obsidian wrote to the file, and our review of editing in Obsidian compares it with Live Preview.

Obsidian also accepts JSON between the dashes:

---
{
  "tags": ["meeting"],
  "attendees": 4
}
---

The docs say a JSON block is read, interpreted and saved as YAML. Treat JSON as an import format, not something you'll keep editing.

Obsidian Property Types and the YAML Each One Writes

Every property has a type, which controls the input Obsidian shows and how it handles the value. Click the icon next to a property name to change its type. Once a name has a type, every note in the vault uses that type for that name. Obsidian keeps this vault-wide map in a types.json file inside your config folder (.obsidian by default).

TypeYAML on diskWhat Obsidian does with it
Textsource: "[[Atomic Habits]]"One line of text; URLs and quoted links work
List- value lines under the keySeveral values, one per line
Numberpages: 320A literal integer or decimal, no expressions
Checkboxfinished: falseShows a checkbox in Live Preview
Datestarted: 2026-10-02Date picker; links to that day's daily note when Daily notes is on
Date & timereview: 2026-11-20T09:30:00Date plus a time of day
Tags- reading lines under tagsReserved for the tags property only

Here's one note header that uses all seven types:

---
source: "[[Atomic Habits]]"
authors:
  - James Clear
pages: 320
finished: false
started: 2026-10-02
review: 2026-11-20T09:30:00
tags:
  - reading
  - habits
---

In Source mode this is exactly the front matter Obsidian stores in the file. In the panel, finished appears as a checkbox and started as a date field, as long as those names carry the Checkbox and Date types in your vault. The date picker displays dates in your operating system's format, but the file stores them as YYYY-MM-DD.

Text properties have two limits. Markdown formatting inside them isn't rendered, and a hashtag in a text value doesn't create a tag. Put tags in the tags list instead.

The Reserved Keys: tags, aliases and cssclasses

Obsidian ships three default properties, and all three are lists:

  • tags groups notes by topic. Write the values without the #.
  • aliases gives a note alternative names that show up in link suggestions and unlinked mentions.
  • cssclasses adds classes to the note, so a CSS snippet can restyle that page alone.

The singular forms tag, alias and cssclass were deprecated in Obsidian 1.4. Obsidian 1.9.0 removed support for them, and its changelog adds a second rule: the values must be lists. A plain text value isn't recognised any more, so templates copied from older guides can quietly stop working.

# Before: ignored since Obsidian 1.9
tag: reading
alias: Habits book
cssclass: wide

# After
tags:
  - reading
aliases:
  - Habits book
cssclasses:
  - wide

To fix a whole vault at once, use the Format converter core plugin. Run Format converter: Frontmatter migration from the command palette, then Start conversion. It changes every note in the vault, so back up first, as the help page advises.

Obsidian Publish reads five more keys (publish, permalink, description, image and cover), which only matter if you publish a vault with that service.

How Do You Write a List Property in Obsidian?

A list property puts each value on its own line under the key, starting with a hyphen and a space. That's the form the Obsidian Properties docs use in their YAML list examples. YAML's one-line [a, b] syntax is valid too, and the frontmatter guide linked earlier compares the two forms. Our YAML list syntax guide goes further, with indentation rules and the mistakes that break a list.

Obsidian adds three rules of its own for list values:

  • Leave the # off tags. In YAML, a # after a space starts a comment, so - #reading stores an empty item instead of a tag.
  • Quote every link. Unquoted, YAML reads [[Deep Work]] as a list inside a list, not as a link.
  • Use a slash for nested tags. - reading/nonfiction creates a nonfiction tag under reading.
related:
  - "[[Deep Work]]"
  - "[[Make Time]]"
tags:
  - reading/nonfiction
  - habits

This produces a related list with two working internal links and two tags, one of them nested.

Links, Nested Objects and Other Obsidian Front Matter Gotchas

Internal links in properties must sit inside double quotes. Obsidian adds the quotes when you type a link into the panel, but a templating plugin writes exactly what your template contains. If a template inserts source: [[Atomic Habits]] without quotes, the value becomes a nested list and the link breaks.

Nested objects are the second trap. YAML lets you indent keys under a parent, as below, but the properties panel doesn't support nested properties. The Obsidian docs recommend Source mode for viewing them.

rating:
  score: 4
  reread: true

That's a real limitation if you're used to nested config in static site generators. Dataview can still read rating.score, but we flatten instead. Two top-level properties, rating: 4 and reread: true, work in the panel, in search and in Bases.

Two smaller rules round this out. Each property name must be unique within a note, so you can't have two tags keys. And bulk edits are limited. The All properties view can rename a property across the vault, but for bigger changes the docs point you to scripts, a code editor or community plugins.

Our own editor's preview doesn't render front matter or wikilinks, so check properties in Obsidian itself. If a note has to work outside Obsidian, the Obsidian to Markdown converter turns wikilinks, callouts and other Obsidian syntax in one pasted note into standard Markdown.

Using Obsidian Properties in Search, Bases and Dataview

Core search has its own property syntax, documented on the Obsidian Search help page:

  • [status] finds notes that have a status property.
  • [status:reading] finds notes where status is reading.
  • [status:reading OR finished] matches either value.
  • [pages:>300] compares numbers.
  • [aliases:null] finds notes where the property exists but has no value.

The null check works on aliases: with nothing after it, but not on empty quotes or empty brackets. In the sidebar, the All properties view lists every property with its type. Clicking one opens search with this syntax filled in.

Bases is a core plugin introduced in Obsidian 1.9. It shows notes as database-style views, such as tables and cards, that you filter and sort by property. The data still lives in each note's YAML, so nothing is locked inside the base.

Dataview, a community plugin, turns every front matter field into a queryable field. Keys with spaces or capitals also get a sanitised name in lowercase with dashes, so Date Read becomes date-read. The Dataview metadata docs explain the rules.

```dataview
TABLE authors, pages, started
FROM #reading
WHERE finished = false
SORT started DESC
```

That query lists every unfinished reading note, most recently started first. For other query types, see the Dataview section of our Obsidian Markdown cheat sheet.

We prefer a small, fixed set of typed properties for each kind of note over free-form keys. Search, Bases and Dataview all match on names and types. If one note says due and another says deadline, every query needs two conditions instead of one.

Obsidian Front Matter Example: A Reusable Note Header

Here's a project note header you can copy into a template:

---
aliases:
  - Site redesign
tags:
  - project
  - work/web
cssclasses:
  - wide-table
status: active
owner: "[[Priya Shah]]"
due: 2026-12-15
budget: 4000
approved: true
---

What Obsidian does with each line:

  • aliases puts this note in link suggestions when you type [[Site redesign.
  • tags uses the Tags type, and work/web is a nested tag.
  • cssclasses only has an effect if a CSS snippet or theme in your vault styles .wide-table.
  • status is Text, so [status:active] finds the note in search.
  • owner is a quoted link, so it stays a working internal link.
  • due is a Date, budget is a Number and approved is a Checkbox.

Save it in your templates folder and insert it with the core Templates plugin. Obsidian merges the template's properties with any the note already has.

If you also publish notes to a static site, our front matter generator builds generic YAML, TOML or JSON with presets for Hugo, Jekyll, Astro and others. It has no Obsidian preset, so paste its output into a note, then set the types and the three list keys in Obsidian.

Good Obsidian front matter comes down to a few habits: plural list keys, quoted links, flat values and one type per property name. Get those right and search, Bases and Dataview all read your notes the same way. You can draft a note's body in our free Markdown editor with a live preview. Then paste it into Obsidian and add the properties there, since our preview doesn't render YAML.