# JSON Format for Output

This document explains how to configure JSON output for any Monad output component that supports the JSON format.

## Overview

Monad provides flexible JSON formatting options to structure your output data in various ways, including nested JSON objects, JSON arrays, and line-delimited JSON (JSONL). Each format serves different integration needs based on your downstream systems.

## Format Types

Monad supports three JSON format types:

| Format Type | Description | File Extension |
|-------------|-------------|----------------|
| `array` | Outputs data as a JSON array of objects (default) | `.json` |
| `nested` | Wraps your data array inside a named root object | `.json` |
| `line` | Creates line-delimited JSON (JSONL) with one object per line | `.jsonl` |

## Configuration Options

When configuring JSON output in Monad, you need to specify:

```json
{
  "type": "[format_type]",
  "key": "[root_key_name]"
}
```

### Parameters

| Parameter | Description | Required | Default |
|-----------|-------------|----------|---------|
| `type` | The format type: `array`, `nested`, or `line` | Yes | - |
| `key` | The name of the root object key (required for `nested` format only) | Only for `nested` format | - |

## Format Examples

### Array Format

The `array` format outputs data as a standard JSON array of objects. This is the default format if none is specified.

**Configuration:**
```json
{
  "type": "array"
}
```

**Example Output:**
```json
[
  {"name": "John", "age": 30},
  {"name": "Alice", "age": 25}
]
```

### Nested Format

The `nested` format wraps your data inside a named root object. This is useful when the receiving system expects a specific JSON structure.

**Configuration:**
```json
{
  "type": "nested",
  "key": "users"
}
```

**Example Output:**
```json
{
  "users": [
    {"name": "John", "age": 30},
    {"name": "Alice", "age": 25}
  ]
}
```

### Line Format (JSONL)

The `line` format creates line-delimited JSON with one object per line. This format is optimal for streaming and processing large datasets where each record can be handled independently.

**Configuration:**
```json
{
  "type": "line"
}
```

**Example Output:**
```
{"name": "John", "age": 30}
{"name": "Alice", "age": 25}
```

## When to Use Each Format

- **Array Format**: Use when you need a standard JSON array structure or when the downstream system expects a complete array of objects.

- **Nested Format**: Use when your destination requires a specific root key containing the data array, such as when integrating with APIs that expect a particular JSON structure.

- **Line Format (JSONL)**: Use for large datasets or streaming applications where processing one record at a time is more efficient than loading the entire array. Also ideal for systems that support appending to existing files.

## Tips and Best Practices

1. **Performance Considerations**: For large datasets, the `line` format offers better performance as it allows processing one record at a time without loading the entire dataset into memory.

2. **File Size**: The `line` format typically results in slightly