Add a schema#

JSON Schema is how Katalyst validates the shape of an item’s frontmatter: required keys, types, ranges. This guide registers a schema and binds it to a collection.

1. Write the schema file#

Put a JSON Schema (draft 2020-12) under .katalyst/schemas/. Its name is the filename stem: book.yaml registers a schema named book, with no separate registration step. Schemas are written in YAML by default, the same draft 2020-12 vocabulary as JSON:

# .katalyst/schemas/book.yaml
$schema: https://json-schema.org/draft/2020-12/schema
title: book
type: object
required: [title, year]
properties:
  title: { type: string, minLength: 1 }
  year:  { type: integer, minimum: 0 }

The name, not the path, is the stable handle the rest of the config uses, so the file is free to move as long as its stem stays the same. To keep schemas as literal .json files instead, set schemas.format to json (or both) in .katalyst/config.yaml; otherwise the directory scan only picks up .yaml/.yml.

2. Bind it to a collection#

The shortest way is the schema: shorthand, which adds a single object check:

# .katalyst/bases/local.yaml
type: filesystem
root: .
collections:
  books:
    path: notes/books
    schema: book

Equivalently, add an explicit object check to checks, useful when you mix it with markdown or filesystem checks:

# .katalyst/bases/local.yaml — under collections: books:
path: notes/books
checks:
  - kind: object
    schema: book
  - kind: markdown_title_matches_h1

With the schema bound, katalyst check books validates each item’s frontmatter against it. A complete item reports OK; one missing a required key fails with a pointer to the offending object and a non-zero exit:

<project>/notes/books/dune.md: OK
<project>/notes/books/foundation.md: /: missing property 'year'
exit status 1

3. Override per file or per run#

A single document can opt into a different registered schema with an inline key in its frontmatter:

---
schema: strict-book
title: Dune
---

And --schema <path> overrides resolution for every selected item in one run:

katalyst check books --schema ./schemas/strict-book.json

The precedence is --schema > inline schema: key > the collection’s object check. See the configuration reference for the key surface, or Collections for why.

Add a schema#

1. Write the schema file#

2. Bind it to a collection#

3. Override per file or per run#

See also#