Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.kiwifs.com/llms.txt

Use this file to discover all available pages before exploring further.

Schema validation lets you enforce structure on pages by type. When enabled, every write validates the page’s frontmatter against a JSON Schema before committing. This prevents agents and users from creating malformed pages.

​
How it works

  1. A page is written with a type field in its frontmatter.
  2. KiwiFS looks up .kiwi/schemas/{type}.json.
  3. If the schema exists and enforcement is on, the frontmatter is validated.
  4. Invalid pages are rejected before they reach git.

​
Enabling enforcement

[schema]
enforce = true
When enforce = false (default), schemas are stored but not checked on writes.

​
Creating schemas

Schemas live in .kiwi/schemas/ as standard JSON Schema files. The filename (minus .json) matches the frontmatter type field. 
curl -X PUT 'http://localhost:3333/api/kiwi/schemas/runbook' \
  -H "Content-Type: application/json" \
  -d '{
    "type": "object",
    "required": ["title", "status", "owner"],
    "properties": {
      "title": {"type": "string"},
      "status": {"type": "string", "enum": ["draft", "reviewed", "verified"]},
      "owner": {"type": "string"},
      "review-by": {"type": "string", "format": "date"}
    }
  }'
Now any page with type: runbook in its frontmatter must have title, status, and owner: 
---
type: runbook
title: Deploy Checklist
status: draft
owner: team-platform
---

# Deploy Checklist
...

​
Listing schemas

curl 'http://localhost:3333/api/kiwi/schemas'

["runbook", "concept", "episode"]

​
Reading a schema

curl 'http://localhost:3333/api/kiwi/schemas/runbook'
Returns the raw JSON Schema document.

​
Validation errors

When a write fails validation, you get a 400 response with details: 
{
  "error": "schema validation failed",
  "type": "runbook",
  "violations": [
    "missing required property: owner",
    "status must be one of: draft, reviewed, verified"
  ]
}
Use schemas to standardize page types across your knowledge base. For example, define schemas for runbook, decision, episode, and concept to ensure agents always create well-formed pages.
Last modified on May 4, 2026