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

# JSON

> Read a stream as JSON.

Reads an incoming stream of JSON, such as a downloaded file or an API response, and turns it into items your integration can work with. Use this when the data you receive is JSON. You can either read the whole document at once, which is simplest for normal-sized files, or read it incrementally, which lets you process very large files a piece at a time without loading everything into memory.

This documentation describes: [Schema](/schemas/stream-deserializer/json)

## Fields

**Read method**

Optional

Choose how the file is read. **Whole file (for smaller files)** loads the entire document and then processes it, and lets you set a Pattern to items. **Incremental (for large files)** streams through the document a piece at a time so a very large file never has to fit in memory, and lets you set a Path to incrementally read over instead. Defaults to Whole file.

**Pattern to items**

Optional

Shown when the read method is Whole file. A dot-notated path to the list inside the JSON that holds the items you want to process, so each item in that list becomes a separate entity. Leave it empty to treat the whole document as a single item. For example, use `data` to read the items from `{"data": [ ... ]}`, or `response.products` for `{"response": {"products": [ ... ]}}`. Do not add `*`; the system steps through the list for you.

**Path to incrementally read over**

Optional

Shown when the read method is Incremental. A selector describing the point in the document to stream over. The supported selectors are documented in the [json-decode-stream selectors guide](https://github.com/klkvsk/json-decode-stream#selectors).

**Input stream is not UTF-8 encoded**

Optional

Turn this on when the incoming data uses a character encoding other than UTF-8, so accented and special characters come through correctly. It reveals two more settings: the encoding the data is currently in, and how to handle characters that cannot be converted.

**Input encoding**

Optional

Shown when the input is not UTF-8. The character encoding the incoming data is currently in. Choose from UTF-16, ISO-8859-1, or Windows-1252.

**On unconvertible characters**

Optional

Shown when the input is not UTF-8. What to do with characters that have no UTF-8 equivalent: NONE keeps them as-is, IGNORE drops them, and TRANSLIT replaces them with the closest available character.

## Sample data

This format reads an incoming stream, so it is selected on a step that fetches a file or a response (for example reading a file from a folder) rather than run on data you already have. The example below shows the JSON it reads and the items it produces with the settings listed.

| Field | Value |
| - | - |
| Read method | Whole file |
| Pattern to items | `products` |

Input (the JSON in the stream):

```json theme={null}
{
  "products": [
    { "sku": "A1", "name": "Wool scarf" },
    { "sku": "B2", "name": "Leather belt" }
  ]
}
```

Output (one item per entry in the matched list):

```json theme={null}
{ "sku": "A1", "name": "Wool scarf" }
{ "sku": "B2", "name": "Leather belt" }
```

```json Configuration theme={null}
{
  "prototype": "json",
  "parameters": {
    "readMethod": "wholeFile",
    "pattern": "products"
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.