Skip to content
Kirak Docs

Changing a Config Schema

The shapes of a project’s config files are JSON Schemas in kirak/schemas/:

File Schema
models.json (all models in one file) models.schema.json
models/<name>.json (one model) model.schema.json
kirak.json, kirak.local.json manifest.schema.json
agents/<name>.json agent.schema.json
the tools map of a file that offers tools (MCP server files) tools.schema.json, $ref’d by that file’s schema; ref checks in kirak/core/tool_declarations.py

Startup, kirak validate, kirak schema (the copies in a project’s .kirak/), kirak modules (each module’s settings) and the generated settings tables in these docs all read these files. Change the schema and the code that reads the key; nothing else repeats the key list.

Adding or changing a key

Section titled “Adding or changing a key”
File Change
kirak/schemas/<name>.schema.json The key, its type, and a description that states the default
The code that reads it For kirak.json, the section’s dataclass in kirak/core/manifest.py too
kirak/validation/ Only for rules beyond shape (references to other files, installed extras). Each new problem code goes in kirak/core/problem_codes.py
Docs The module or concept page, when behavior changes. Settings tables are generated: run python scripts/gen_reference.py
CHANGELOG.md An entry

A schema can give a friendlier message for a keyword with x-kirak-errors on the key, for example "x-kirak-errors": {"pattern": "'name' must be lowercase letters, digits, and hyphens."}.

Removing or renaming a key

Section titled “Removing or renaming a key”

Unknown keys are rejected, so a project that still has the old key fails at startup. Tell its owner what to do instead:

  • kirak.json: add the key to _RETIRED_KEYS (or _RETIRED_TOP_LEVEL_KEYS) in kirak/core/manifest.py, with the replacement; startup and kirak validate report retired_key with that message.
  • Model and agent files: add a check with its own code in kirak/validation/models.py or agents.py (see removed_auth_block).
  • CHANGELOG.md: a Breaking entry with the migration.

Tests

Section titled “Tests”
  • tests/test_core/test_schema_files.py – every key has a description, each kirak.json section matches its dataclass, the example projects validate.
  • tests/test_catalog/test_generated_docs.py – the generated tables are current.

Projects that exported the schemas into .kirak/ get a startup warning until they run kirak schema again.