Structured output (JSON Schema)

kanros lets you constrain a model's output to a JSON Schema. When the schema is set, the provider configures the API to enforce structured output and kanros validates the response before returning it to the runner.

Configuration

Attach a JSON Schema under providers[].config.response_schema, or set it on a CompletionRequest directly:

providers:
  - id: openai:gpt-4o-mini
    config:
      api_key: env:OPENAI_API_KEY
      response_schema:
        type: object
        properties:
          name:    {type: string}
          age:     {type: number}
          email:   {type: string, format: email}
        required: [name, age]
        additionalProperties: false

When response_schema is non-null, kanros sets:

  • OpenAI: response_format = { "type": "json_schema", "json_schema": { "schema": ..., "strict": true } } — uses OpenAI's native structured outputs feature.
  • Anthropic: a single forced tool named kanros_structured_output is registered with the schema as its input_schema, and tool_choice is pinned to that tool. The model's reply lives in the tool's input payload, which kanros promotes back into the completion.content field.

Validation

Independent of the wire-level enforcement, kanros validates the response against the schema using jsonschema. A failure produces ProviderError::SchemaViolation with a details field listing up to five failures:

schema violation from `openai:gpt-4o-mini`: 42 is not of type "string" at /name

Retry policy applies — SchemaViolation is not a retryable error, because retrying a deterministic schema mismatch wastes tokens.