> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upsonic.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# JSON Loader

> Load JSON and JSONL files with flexible record extraction

## Overview

JSON loader processes JSON and JSONL files with support for single or multi-document extraction using JQ queries. Flexible content and metadata mapping for structured data.

**Loader Class:** `JSONLoader`

**Config Class:** `JSONLoaderConfig`

## Install

<Note>
  Install the JSON loader optional dependency group:

  ```bash theme={null}
  uv pip install "upsonic[json-loader]"
  ```
</Note>

## Examples

```python theme={null}
from upsonic import Agent, Task, KnowledgeBase
from upsonic.loaders.json import JSONLoader
from upsonic.loaders.config import JSONLoaderConfig
from upsonic.embeddings import OpenAIEmbedding, OpenAIEmbeddingConfig
from upsonic.text_splitter.recursive import RecursiveChunker, RecursiveChunkingConfig
from upsonic.vectordb import ChromaProvider, ChromaConfig, ConnectionConfig, Mode

# Configure loader for multi-document extraction
loader_config = JSONLoaderConfig(
    mode="multi",
    record_selector=".articles[]",
    content_mapper=".title + ' ' + .body",
    metadata_mapper={"author": ".author", "date": ".published"}
)
loader = JSONLoader(loader_config)

# Setup KnowledgeBase
embedding = OpenAIEmbedding(OpenAIEmbeddingConfig())
chunker = RecursiveChunker(RecursiveChunkingConfig())
vectordb = ChromaProvider(ChromaConfig(
    collection_name="json_data",
    vector_size=1536,
    connection=ConnectionConfig(mode=Mode.IN_MEMORY)
))

kb = KnowledgeBase(
    sources=["articles.json"],
    embedding_provider=embedding,
    vectordb=vectordb,
    loaders=[loader],
    splitters=[chunker]
)

# Query with Agent
agent = Agent("anthropic/claude-sonnet-4-5")
task = Task("Find articles about AI", context=[kb])
result = agent.do(task)
print(result)
```

## Parameters

| Parameter                | Type                            | Description                                     | Default  | Source   |
| ------------------------ | ------------------------------- | ----------------------------------------------- | -------- | -------- |
| `encoding`               | `str \| None`                   | File encoding (auto-detected if None)           | None     | Base     |
| `error_handling`         | `"ignore" \| "warn" \| "raise"` | How to handle loading errors                    | "warn"   | Base     |
| `include_metadata`       | `bool`                          | Whether to include file metadata                | True     | Base     |
| `custom_metadata`        | `dict`                          | Additional metadata to include                  | {}       | Base     |
| `max_file_size`          | `int \| None`                   | Maximum file size in bytes                      | None     | Base     |
| `skip_empty_content`     | `bool`                          | Skip documents with empty content               | True     | Base     |
| `mode`                   | `"single" \| "multi"`           | Processing mode                                 | "single" | Specific |
| `record_selector`        | `str \| None`                   | JQ query to select records (required for multi) | None     | Specific |
| `content_mapper`         | `str`                           | JQ query to extract content                     | "."      | Specific |
| `metadata_mapper`        | `dict[str, str] \| None`        | Map metadata keys to JQ queries                 | None     | Specific |
| `content_synthesis_mode` | `"json" \| "text"`              | Format for extracted content                    | "json"   | Specific |
| `json_lines`             | `bool`                          | File is in JSON Lines format                    | False    | Specific |