How to Configure LangExtract's Format Handler for JSON vs YAML

Use the FormatHandler class from langextract/core/format_handler.py and set format_type to data.FormatType.JSON or data.FormatType.YAML, along with optional flags like use_fences and use_wrapper to control how model outputs are wrapped and parsed.

LangExtract centralizes output formatting through a single configuration object. The FormatHandler class determines whether your extractions use JSON or YAML serialization, how prompts are fenced with markdown code blocks, and whether results are wrapped in container dictionaries. This guide explains how to configure LangExtract's format handler for both JSON and YAML outputs using the actual source implementation from google/langextract.

FormatHandler Configuration Parameters

The constructor in langextract/core/format_handler.py (lines 66-74) accepts these key arguments:

• format_type — Set to data.FormatType.JSON or data.FormatType.YAML to define the serialization format.
• use_wrapper — Boolean flag to wrap extractions in a container dictionary like {"extractions": [...]}.
• wrapper_key — String defining the dictionary key when use_wrapper=True (default: "extractions").
• use_fences — Boolean to wrap prompts and expected outputs in markdown code fences (e.g., ```json).
• attribute_suffix — Suffix for attribute fields (default: "_attributes").
• strict_fences and allow_top_level_list — Fine-grained validation controls for parsing edge cases.

Configuring JSON Output

To extract structured data in JSON format with fenced code blocks:

from langextract.core import format_handler
from langextract.core.data import FormatType

handler = format_handler.FormatHandler(
    format_type=FormatType.JSON,
    use_fences=True,
    use_wrapper=True,
    wrapper_key="extractions"
)

This configuration ensures that prompts include ```json fences and that the model returns wrapped JSON objects under the "extractions" key.

Configuring YAML Output

For YAML serialization, change the format_type while keeping other flags consistent:

from langextract.core import format_handler
from langextract.core.data import FormatType

handler = format_handler.FormatHandler(
    format_type=FormatType.YAML,
    use_fences=True,
    use_wrapper=False  # Optional: return raw list instead of wrapped dict

)

When use_fences=True, the handler generates prompts with ```yaml code blocks and expects the model to return fenced YAML content.

Advanced Wrapper and Validation Settings

The FormatHandler supports complex extraction scenarios through additional parameters.

Container Wrappers

Set use_wrapper=True to enforce a consistent top-level structure across all extractions. The wrapper_key parameter customizes the container dictionary key:

handler = format_handler.FormatHandler(
    format_type=FormatType.JSON,
    use_wrapper=True,
    wrapper_key="results"  # Changes default from "extractions" to "results"

)

Parsing Validation

The strict_fences parameter enforces that model outputs must contain properly formatted markdown fences. Set allow_top_level_list=True when expecting the model to return a raw JSON array or YAML sequence without a wrapping object.

Internal Implementation Details

The FormatHandler class orchestrates serialization through two primary methods defined in langextract/core/format_handler.py.

Serialization with format_extraction_example

The format_extraction_example() method (lines 16-50) handles example serialization for prompts. It selects between json.dumps and yaml.safe_dump based on self.format_type, optionally adds the wrapper dictionary, and applies markdown fences when self.use_fences is enabled.

Parsing with parse_output

The parse_output() method extracts fenced content from model responses, strips the fences if present, and delegates to the appropriate parser (JSON or YAML) based on the configured format_type. This ensures consistent handling regardless of whether the model included extra whitespace or commentary outside the fences.

Summary

• The FormatHandler in langextract/core/format_handler.py centralizes JSON and YAML configuration through the format_type parameter using data.FormatType.JSON or data.FormatType.YAML.
• Enable use_fences=True to wrap prompts and expected outputs in markdown code blocks appropriate to the format.
• Control output structure with use_wrapper and wrapper_key to enforce container dictionaries around extraction results.
• The handler automatically selects json.dumps or yaml.safe_dump during prompt generation and uses corresponding parsers when processing model outputs.

Frequently Asked Questions

How do I switch between JSON and YAML in LangExtract?

Instantiate FormatHandler with format_type=FormatType.JSON for JSON output or format_type=FormatType.YAML for YAML output. Both formats support identical wrapper and fencing options, allowing you to change only the serialization method without modifying other extraction logic.

What is the difference between use_wrapper and use_fences in LangExtract?

use_wrapper controls the data structure, wrapping extractions in a dictionary like {"extractions": [...]}, while use_fences controls the text formatting, adding markdown code blocks (json or yaml) around the serialized content in prompts and expected model responses.

Can LangExtract parse YAML without fences?

Yes. Set use_fences=False when creating the FormatHandler. The parse_output method will then attempt to parse the raw model output directly as YAML, though this requires the model to return clean YAML without markdown formatting or explanatory text.

Where is the FormatHandler class defined in the LangExtract repository?

The FormatHandler class is defined in langextract/core/format_handler.py in the google/langextract repository. The constructor signature and default parameters are located at lines 66-74, with serialization logic in format_extraction_example() at lines 16-50.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}