Link Search Menu Expand Document

Schemas

As you end up creating more notes, it can be hard to keep track of it all. This is why Dendron has schemas to help you manage your notes at scale. Think of schemas as an optional type system for your notes. They describe the hierarchy of your data and are themselves, represented as a hierarchy.

Schemas show up as icons next to lookup results.

Why Use Schemas

Schemas help you categorize your notes by making sure your hierarchies are consistent with one another.

For example, lets say you have a bunch of projects and you know you like to keep your projects in the following hierarchy

.
└── project
    β”œβ”€β”€ retrospective
    β”œβ”€β”€ people
    β”œβ”€β”€ todo
    └── meet

Schemas will autosuggest valid children when you create a new project.

If you accidentally do a typo, your schema will let you know that you have an inconsistency.

Schema Anatomy

A schema is a YAML file with the following naming scheme {name}.schema.yml

Below is an example of a four-level hierarchy describing cli commands. The id field of the schema is used to build a glob pattern which will be used to match notes matching the schema.

version: 1
schemas:
# this will match "cli.*" notes
- id: cli 
  # human readable description of hierarchy
  desc: command line interface reference
  # add this to the domain of your schema hierarchy
  parent: root
  # when a schema is a namespace, it can have arbitrary children. equivalent to cli.* glob pattern
  namespace: true 
  children:
    - cmd
    - env
# will match cli.*.env
- id: env
  desc: cli specific env variables
# will match cli.*.cmd.*
- id: cmd
  desc: subcommands 
  namespace: true

Below is another way of representing the above schema

.
└── cli # matches cli
    └── {cli child} # matches cli.*
        β”œβ”€β”€ env # matches cli.*.env
        └── cmd # matches cli.*.cmd
            └── {cmd child} # matches cli.*.cmd.*

Schema Properties

version (optional): number

  • values: 0|1
  • default: 0
  • description: schema version number

imports (optional): str[]

  • values: list of schemas to import
  • default: []
  • description: import schemas from another schema into the current schema
    • when using schemas from an external schema file, you will need to prefix the schema with the file name without the schema.yml suffix
  • NOTE: import is only available in schema version 1

Example:

  • foo.schema. yml
version: 1
imports:
- bar
schemas:
- id: foo
  parent: root
  children:
    - bar.bar # notice that we prefix the id bar with the filename
  • bar.schema.yml
version: 1
schemas:
- id: bar
  parent: root
  children: 
    - one
- id: one

The above would match the following files

foo.bar # match
foo.bar.one #match

schemas

  • list of schema entities

id

the identifier of the schema. also designates the glob pattern match. this is the only required part of a schema. all other fields are optional

desc

human readable description of the schema node. these will automatically when creating notes that match the schema.

parent

only required for schema domain

namespace

making a schema node a namespace automatically brings its immediate children as part of the schema, even if they are not explicitly defined in the schema definition. it will also automatically set the pattern to {namespace}.*

  • example:
schemas:
- id: project
  parent: root
  namespace: true
  • this will match:
    • project
    • project.foo
    • project.bar
  • it will not match
    • project.foo.bar

pattern

glob pattern that schema matches. by default, this is the id of the schema. you can override this.

For example, take a look at the journal schema below

schemas:
- id: journal
  title: journal
  desc: ""
  parent: root
  children:
    - year
- id: year
  title: year
  pattern: "[0-2][0-9][0-9][0-9]"
  children: 
    - month
- id: month
  title: month
  pattern: "[0-9][0-9]"
  children: 
    - day
- id: day
  title: day
  pattern: "[0-9][0-9]"
  namespace: true

This will match the following queries

# journal
# journal.2020
# journal.2020.09
# journal.2020.09.12
# journal.2020.09.12.foo.md

children

list of ids of schemas that are the child of the current schema

template

a template you can apply to all notes that match this schema

template:
  # identifier for the template (for a note based template, it would be the name of the note)
  id: journal.template.daily
  # what sort of template we are creating. currently, only 'note' is supported
  type: note

Schema Templates

Schema templates let you specify a pre-defined template that will automatically be applied to all notes that match the template. You can see a video of how this works below.

This is extremely useful whenver you want to re-use the outline of a note. Examples include daily journals, weekly shopping lists, and weekly reviews.

NOTE: you’ll need to run > Dendron: Reload Index whenever you updated your schema for the changes to take effect.

Stubs

Stubs are notes that don’t exist but will show up in lookup results. There are two reasons why these notes might show up:

  • they are the parent of a note deeper in the hierarchy (eg. foo.bar might be a stub for foo.bar.foobar)
  • they are possible notes according to the schema

The + sign next to the suggestion indicates that the note is a stub and does not exist

Unknown Schema

Dendron doesn’t force you to use schemas if you don’t want to. This is why you can create notes that don’t match any schema. Dendron will show you a ? next to these results.

Sometimes rules schemas are meant to be broken

Working with Schemas

Schemas can be modified, created and deleted using the same lookup interface that you use for regular notes. See lookup for further details about working with schemas.

Example Schemas