Struct StructuredOutputSpec 

pub struct StructuredOutputSpec {
    pub schema: Option<SchemaRef>,
    pub from_example: Option<SchemaRef>,
    pub enable_extractor: Option<bool>,
    pub enable_tool_injection: Option<bool>,
    pub enable_retry: Option<bool>,
    pub enable_repair: Option<bool>,
    pub max_retries: Option<u8>,
    pub repair_model: Option<String>,
    pub strict: Option<bool>,
}

Structured output configuration for a task

Controls how the StructuredOutputEngine validates and repairs output. Supports shorthand (just schema path) or full configuration.

Examples

Shorthand (schema file path):

structured: ./schemas/user.json

Full configuration:

structured:
  schema: ./schemas/user.json
  max_retries: 3
  enable_repair: true
  repair_model: claude-sonnet-4-6

Inline schema:

structured:
  schema:
    type: object
    properties:
      name:
        type: string
    required: [name]

Fields

schema: Option<SchemaRef>

JSON Schema reference (inline or file path).

None when from_example is set — schema is derived at runtime. Use StructuredOutputEngine::load_schema() which handles derivation correctly.

from_example: Option<SchemaRef>

JSON example — Nika auto-derives the JSON Schema from this at runtime.

Mutually exclusive with schema. When set, schema is a placeholder {}. The engine calls json_to_schema() on the example before any validation.

enable_extractor: Option<bool>

Enable Layer 1: rig Extractor (Rust type extraction) Default: true

enable_tool_injection: Option<bool>

Enable Layer 0: Tool injection (DynamicSubmitTool) When true, injects a synthetic submit_result tool for provider-side schema enforcement before falling through to post-processing layers. Default: true

enable_retry: Option<bool>

Enable Layer 3: Retry with feedback Default: true

enable_repair: Option<bool>

Enable Layer 4: LLM repair Default: true

max_retries: Option<u8>

Maximum retry attempts (Layer 3) Default: 2

repair_model: Option<String>

Model to use for repair (Layer 4) Default: same as task model

strict: Option<bool>

When true, derived from_example schemas add additionalProperties: false to all object schemas recursively. Prevents the LLM from injecting extra keys. Default: false. Only meaningful when from_example is set.

Implementations

impl StructuredOutputSpec

pub fn with_schema(schema: SchemaRef) -> StructuredOutputSpec

Create with a schema reference

pub fn with_example_file(path: impl Into<String>) -> StructuredOutputSpec

Create with an example file (schema derived at runtime).

The file is read at execution time and its JSON structure is used to derive the JSON Schema for output validation.

NOTE: The LLM prompt will NOT include the example structure — only a generic “output valid JSON” instruction. Use with_example_inline() when you want the example shown in the prompt.

pub fn with_example_inline(example: Value) -> StructuredOutputSpec

Create with an inline JSON example (schema derived at runtime).

The example structure is injected into the LLM prompt AND used for validation. This gives the LLM full context about the expected output shape.

pub fn with_inline_schema(schema: Value) -> StructuredOutputSpec

Create with an inline JSON schema

pub fn with_file_schema(path: impl Into<String>) -> StructuredOutputSpec

Create with a file path

pub fn max_retries_or_default(&self) -> u8

Get max_retries with default

pub fn enable_tool_injection_or_default(&self) -> bool

Check if Layer 2 (tool_use) is enabled

pub fn enable_retry_or_default(&self) -> bool

Check if Layer 3 (retry) is enabled

pub fn enable_repair_or_default(&self) -> bool

Check if Layer 4 (repair) is enabled

pub fn to_output_policy(&self) -> OutputPolicy

Convert to OutputPolicy for executor Layer 0 dispatch.

The executor’s run_infer() uses OutputPolicy to trigger Layer 0 tool injection and prompt schema instructions. This bridges structured: config to that path. The original spec is preserved in source_structured_spec so that to_structured_spec() can roundtrip without losing layer toggle config.

Trait Implementations

impl Clone for StructuredOutputSpec

fn clone(&self) -> StructuredOutputSpec

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for StructuredOutputSpec

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for StructuredOutputSpec

fn deserialize<D>( deserializer: D, ) -> Result<StructuredOutputSpec, <D as Deserializer<'de>>::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for StructuredOutputSpec

fn serialize<__S>( &self, __serializer: __S, ) -> Result<<__S as Serializer>::Ok, <__S as Serializer>::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.