Use this reference while editing a Recipe for Sonny 0.12.7. The
downloadable JSON schema
is the exact
output of the installed release’s sonny schema-gen command. It describes the
nested field shapes, including Sonny’s extensions. It is not a complete runtime
permission policy or a substitute for the release’s validator.
Required, default and optional are different
The emitted JSON schema requires document-root version, pack and prompts.
Runtime validation adds semantic requirements: an ID, a usable entry prompt,
valid selected-profile references and consistent policy fields. An editor
accepting a file against JSON schema does not establish those conditions.
Use version: 2 for new files. An omitted pack.kind follows the primary-Recipe
behavior; the tutorial states kind: primary explicitly. A profile ID named
default has no special authority unless selected by default_llm_profile_id.
An omitted or empty tool allowlist does not mean no tools. Use the tested
--no-tools headless mode when a task needs no tool execution, and inspect the
actual tool policy for tool-enabled work.
Fields below are structurally optional unless the root or semantic rules
require them. “Optional” does not promise that a feature is available in every
client. An absent JSON default annotation does not establish an empty runtime
value: loading, inheritance, host policy and command flags also participate.
The nested schema supplies the exact types; the guides explain their behavior.
Document root
| Field | Structural requirement | Meaning |
|---|---|---|
version | Required integer | Format version; not the Recipe’s own release number. |
pack | Required object | Identity, profiles, policy and composition metadata. |
prompts | Required array | Prompt definitions; the entry prompt must resolve. |
decision_policy | Optional extension | Versioned policy reference; validate its closure and module pins separately. |
Pack fields
These rows are generated from the installed schema’s pack.properties map.
They enumerate shape, not defaults or proof of feature availability.
| Field | JSON type |
|---|---|
agents | object |
auto_models | array |
compose | object |
conditions | array |
context | object |
context_profiles | array |
critics | array |
datasets | array |
default_context_profile_id | string |
default_fallback_models | array |
default_io | object |
default_llm_profile_id | string |
eval_suites | array |
id | string |
includes | array |
kind | string |
llm_profiles | array |
locale | string |
lsp | object |
mcp | object |
memory | object |
metadata | object |
output_contract | object |
pack_eval_suite | object |
parent | string |
policy_version | string |
recommended_models | array |
redaction_profiles | array |
requires | object |
secrets | array |
semantic_cache | string |
supported_modalities | array |
tool_efficiency | object |
tools | object |
variables | object |
version | string |
Prompt fields
These rows are generated from prompts.items.properties.
| Field | JSON type |
|---|---|
additional_details | array |
compose | object |
conditions | array |
constraints | object |
context | object |
description | string |
enabled | boolean |
guidelines | array |
id | string |
priority | integer |
ref | string |
responsibilities | array |
system | string |
title | string |
tools | object |
turns | array |
type | string |
Validate the behavior you intend
sonny recipe validate ./brief.yaml
sonny recipe resolve evidence-brief --file ./brief.yaml --format json
The file/ID above refer to the complete research example . Validation checks structure and references; resolution compiles a selected subject. Neither alone proves provider access or successful tool execution. Unknown root fields can warn while validation exits zero; inspect diagnostics. A missing default profile, missing reference or missing required variable can fail at different stages. Preserve the diagnostic rather than repeatedly changing unrelated settings.
Prompt ref files use a smaller fragment shape, not a complete Recipe document.
pack_eval_suite and eval_suites are distinct schemas; their input keys and
graders are not interchangeable. Raw URI extensions also need actual load/request
checks. The emitted JSON schema is deliberately weaker than those semantic and
runtime contracts.
Regenerate when changing releases
sonny --version
sonny schema-gen > recipe-schema.json
sonny variant-schema-gen > recipe-variant-schema.json
Run these against the release you actually deploy, compare the output and rerun
representative fixtures. The archived schema’s SHA256 is
a4f20913f9a4416b61b1622584d6995f4d17030e2c4295c9ba958b8390db33ae.
It is a release snapshot; do not silently replace it with another binary’s output.
The model-variant envelope has its own schema and approval/digest rules.
Continue with authoring , source installation and profile/endpoint setup .