Custom Schemas in Bosun

Bosun uses JSON Schema to make agent outcomes and structured prompts predictable. Whenever you set stop_schema, fail_schema, or a structured prompt returns value, Bosun validates the response against your schema and stores the resulting JSON in outputs and errors for downstream steps.

This guide covers the built-in primitives and shows how to define custom schemas for both agents and structured prompts.

Predefined schema shortcuts

Use the following shortcut keywords when you only need simple, single-field responses. Bosun expands each keyword into a proper JSON Schema before sending the request to the LLM.

Keyword	Underlying schema
string	{ "type": "string" }
integer	{ "type": "integer" }
number	{ "type": "number" }
boolean	{ "type": "boolean" }
string_array	{ "type": "array", "items": { "type": "string" } }
integer_array	{ "type": "array", "items": { "type": "integer" } }
boolean_array	{ "type": "array", "items": { "type": "boolean" } }

These shortcuts work everywhere Bosun accepts a schema: structured_prompt.returns, agent.stop_schema, and agent.fail_schema.

Authoring custom schemas

When you need richer structure—multiple properties, nested arrays, enums—inline a JSON Schema object. Bosun enforces the schema at runtime, so invalid responses fail validation instead of propagating through your workflow.

Structured prompt example

steps:
  - id: release_notes
    structured_prompt:
      prompt: |
        Draft release notes for version {{ inputs.version }}.
      returns:
        type: object
        additionalProperties: false
        required: [summary, highlights]
        properties:
          summary:
            type: string
          highlights:
            type: array
            minItems: 3
            items:
              type: string

outputs.release_notes.highlights is guaranteed to be an array of strings, so later steps can iterate over it without defensive parsing.

Agent stop payload example

steps:
  - id: qa_report
    agent:
      extends: Coding
      instructions: "Run the QA checklist."
      stop_schema:
        type: object
        required: [summary, checks]
        additionalProperties: false
        properties:
          summary:
            type: string
          checks:
            type: array
            items:
              type: object
              required: [name, status]
              properties:
                name:
                  type: string
                status:
                  type: string
                  enum: [pass, fail, blocked]

When the agent calls stop, the structured payload is stored in both the run transcript and outputs.qa_report. You can pass it directly into another prompt or render it in a notification without any manual parsing.

Agent failure payload example

  - id: stabilize_tests
    agent:
      extends: Coding
      instructions: "Fix the flaky tests listed in the issue."
      fail_schema:
        type: object
        required: [summary, retryable, blockers]
        additionalProperties: false
        properties:
          summary:
            type: string
          retryable:
            type: boolean
          blockers:
            type: array
            items:
              type: string

If the agent cannot complete the work, Bosun records the object returned by the task_failed tool under both outputs.stabilize_tests and errors.stabilize_tests[0].reason. A follow-up step can branch on retryable to decide whether to rerun automatically or page a human.

tip

LLMs generally require additionalProperties: false to be set. Default to including it in your schemas to avoid unexpected fields and errors.