JsonSchemaValidator

Validate the JSON content of ChatMessage objects against a specified JSON Schema.

Key Features

• Validates the JSON content of the last message in a list of ChatMessage objects against a JSON schema.
• Routes valid messages to the validated output and invalid messages to the validation_error output.
• Returns structured error messages when validation fails, which can be fed back to an LLM for correction.
• Supports custom error templates for formatting validation error messages.
• Enables LLM recovery loops where the LLM retries producing valid JSON output.

Configuration

1. Drag the JsonSchemaValidator component onto the canvas from the Component Library.
2. Click on the component to open the configuration panel.
3. Configure the component settings:
   • Optionally enter a json_schema to validate messages against.
   • Optionally enter a custom error_template to format validation error messages.

Connections

JsonSchemaValidator receives a list of ChatMessage objects, typically from an LLM or ChatGenerator. It validates the last message in the list.

Connect its validated output to the next component in your pipeline. Connect its validation_error output back to a branch joiner that feeds into the LLM to enable retry loops.

Source Code

To check this component's source code, open json_schema.py in the Haystack repository.

Usage Examples

Basic Configuration

  JsonSchemaValidator:
    type: haystack.components.validators.json_schema.JsonSchemaValidator
    init_parameters: {}

In a Pipeline

This pipeline uses an LLM to extract structured information and return it as JSON. JsonSchemaValidator validates the output against a schema. If validation fails, the error is sent back to the LLM through a BranchJoiner so the LLM can correct its output.

# haystack-pipeline
components:
  branch_joiner:
    type: haystack.components.joiners.branch.BranchJoiner
    init_parameters:
      type_: "typing.List[haystack.dataclasses.ChatMessage]"

  prompt_builder:
    type: haystack.components.builders.chat_prompt_builder.ChatPromptBuilder
    init_parameters:
      template:
      - _content:
        - text: |
            Extract the following information from the text and return it as valid JSON.

            Text: {{ query }}

            Return a JSON object with these fields:
            - "answer": a concise answer to the query (string)
            - "confidence": a confidence score between 0 and 1 (number)
        _role: user

  llm:
    type: haystack.components.generators.chat.openai.OpenAIChatGenerator
    init_parameters:
      model: gpt-4o-mini

  json_validator:
    type: haystack.components.validators.json_schema.JsonSchemaValidator
    init_parameters:
      json_schema:
        type: object
        properties:
          answer:
            type: string
          confidence:
            type: number
            minimum: 0
            maximum: 1
        required:
          - answer
          - confidence

connections:
  - sender: branch_joiner.value
    receiver: prompt_builder.messages
  - sender: prompt_builder.prompt
    receiver: llm.messages
  - sender: llm.replies
    receiver: json_validator.messages
  - sender: json_validator.validation_error  # Retry loop: send errors back to the LLM
    receiver: branch_joiner.value

inputs:
  query:
    - prompt_builder.query

outputs:
  validated_response: json_validator.validated

Parameters

Inputs

Parameter	Type	Default	Description
messages	List[ChatMessage]		A list of ChatMessage instances to be validated. The last message in this list is the one that is validated.
json_schema	Optional[Dict[str, Any]]	None	A dictionary representing the JSON schema against which the messages' content is validated. If not provided, the schema from the component init is used.
error_template	Optional[str]	None	A custom template string for formatting the error message in case of validation. If not provided, the error_template from the component init is used.

Outputs

Parameter	Type	Description
validated	List[ChatMessage]	A list of messages if the last message is valid.
validation_error	List[ChatMessage]	A list of messages if the last message is invalid.

Init Parameters

These are the parameters you can configure in Pipeline Builder:

Parameter	Type	Default	Description
json_schema	Optional[Dict[str, Any]]	None	A dictionary representing the JSON schema against which the messages' content is validated.
error_template	Optional[str]	None	A custom template string for formatting the error message in case of validation failure.

Run Method Parameters

These are the parameters you can configure for the component's run() method. This means you can pass these parameters at query time through the API, in Playground, or when running a job. For details, see Modify Pipeline Parameters at Query Time.

Parameter	Type	Default	Description
messages	List[ChatMessage]		A list of ChatMessage instances to be validated. The last message in this list is the one that is validated.
json_schema	Optional[Dict[str, Any]]	None	A dictionary representing the JSON schema against which the messages' content is validated. If not provided, the schema from the component init is used.
error_template	Optional[str]	None	A custom template string for formatting the error message in case of validation. If not provided, the error_template from the component init is used.