> ## 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

> 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

<Mermaid>
  flowchart LR
  Write\["PUT /file"] --> Check{"frontmatter has\n`type` field?"}
  Check -- No --> Commit\["Git Commit"]
  Check -- Yes --> Validate\["Validate against\nschemas/type.json"]
  Validate -- Pass --> Commit
  Validate -- Fail --> Reject\["400 Bad Request"]
</Mermaid>

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

```toml theme={null}
[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.

```bash theme={null}
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`:

```markdown theme={null}
---
type: runbook
title: Deploy Checklist
status: draft
owner: team-platform
---

# Deploy Checklist
...
```

## Listing schemas

```bash theme={null}
curl 'http://localhost:3333/api/kiwi/schemas'
```

```json theme={null}
["runbook", "concept", "episode"]
```

## Reading a schema

```bash theme={null}
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:

```json theme={null}
{
  "error": "schema validation failed",
  "type": "runbook",
  "violations": [
    "missing required property: owner",
    "status must be one of: draft, reviewed, verified"
  ]
}
```

<Tip>
  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.
</Tip>