Schemas

List, read, and save the JSON Schemas that validate page frontmatter.

A schema is a JSON Schema file at .kiwi/schemas/<type>.json. When enforcement is on, every markdown write is checked against the schema named by the page’s discriminator field (type by default), and invalid writes return 422. See Schemas for how validation works.

.kiwi/config.toml

[schema]
enforce = true
discriminator = "type"     # frontmatter field that picks the schema
enforce_level = "reject"   # or "warn" to log violations and allow the write

List schemas

Return the type names that have a schema file.

GET /api/kiwi/schemas

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

Returns a JSON array of type names. The array is empty when .kiwi/schemas/ does not exist.

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

Get a schema

Return one schema document.

GET /api/kiwi/schemas/:type

type · string · required

Type name. Letters, digits, -, and _ only.

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

Returns 400 for an invalid type name and 404 if no schema exists. The response is the stored JSON Schema.

{
  "type": "object",
  "required": ["title", "status", "owner"],
  "properties": {
    "title": { "type": "string" },
    "status": { "type": "string", "enum": ["draft", "reviewed", "verified"] },
    "owner": { "type": "string" }
  }
}

Save a schema

Create or replace a schema. The body is the JSON Schema document. The validator reloads right away, so the next write uses the new schema.

PUT /api/kiwi/schemas/:type

type · string · required

Type name. Letters, digits, -, and _ only.

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"}
    }
  }'

Returns 400 for an invalid type name or a body that isn’t JSON.

status · string

Always ok.

type · string

Type name saved.

{ "status": "ok", "type": "runbook" }

Schema files live under .kiwi/ and are written directly, not through the write pipeline, so saving a schema does not create a git commit.

Related

Schemas concepts

Discriminators, enforcement levels, and error format.

Files

Writes that schemas validate.