Schema Validation

Enforce structure on your markdown with JSON Schema validation on writes.

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 discriminator field in its frontmatter (default type).
2. KiwiFS looks up .kiwi/schemas/{value}.json.
3. If the schema exists and enforcement is on, the frontmatter is validated.
4. Invalid pages are rejected — or logged when enforce_level = "warn".

Enabling enforcement

[schema]
enforce = true
discriminator = "type"    # or "kind"
enforce_level = "reject"  # or "warn" while you adopt schemas

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 discriminator value — type by default, or whatever you set in [schema] discriminator.

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.