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
- A page is written with a
type field in its frontmatter.
- KiwiFS looks up
.kiwi/schemas/{type}.json.
- If the schema exists and enforcement is on, the frontmatter is validated.
- Invalid pages are rejected before they reach git.
Enabling enforcement
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"}
}
}'
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'
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.
