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

> Configure LangExtract's format handler for JSON or YAML. Learn to control output parsing with flags like use_fences and use_wrapper for efficient data extraction.

- Repository: [Google/langextract](https://github.com/google/langextract)
- Tags: how-to-guide
- Published: 2026-02-16

---

**Use the `FormatHandler` class from [`langextract/core/format_handler.py`](https://github.com/google/langextract/blob/main/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`](https://github.com/google/langextract/blob/main/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:

```python
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:

```python
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:

```python
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`](https://github.com/google/langextract/blob/main/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.