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

# JSON File Reader

> Parse JSON data intelligently with AI-assisted field detection and automatic type mapping

The JSON File Reader transforms raw JSON data into structured, usable objects within your automation workflows. With AI-powered analysis and intelligent type detection, it automatically understands your JSON structure and suggests appropriate field mappings for use in [automation workflows](/workflows/automation-system).

## Key Features

* **AI-Assisted Analysis** – Analyzes JSON structure and suggests field types and mappings
* **Intelligent Type Detection** – Recognizes dates, numbers, text, and boolean values automatically
* **Live Preview** – See how your JSON will be parsed before saving your configuration
* **Multiple Input Sources** – Works with API responses, file uploads, and direct JSON input

## Supported JSON Formats

The JSON File Reader handles flat and nested objects, arrays, and mixed types—including API responses, configuration files, data exports, and webhook payloads. JSON can come from:

* **Text Value Reference** – Direct input or paste
* **API Request Actions** – Responses from external APIs
* **Data Transform Actions** – Output from other automations
* **Record Triggers** – JSON fields from record updates

## Creating a JSON File Reader

<Steps>
  <Step title="Navigate to File Readers">
    In your application, go to **File Readers** section
  </Step>

  <Step title="Create New Reader">
    Click **+ File Reader** and select **JSON** from the document type options
  </Step>

  <Step title="Configure Basic Settings">
    **Name**: Enter a descriptive name (e.g., "API Response Parser")

    **Description**: Optional description for your team
  </Step>

  <Step title="Set Up JSON Analysis">
    The system analyzes your JSON and suggests field types and mappings, with a live preview of parsed data.
  </Step>

  <Step title="Test with Sample JSON">
    Use sample data to validate field extraction and type detection before saving.
  </Step>
</Steps>

## Configuration Options

### Field Type Mapping

The system automatically detects and maps field types:

<AccordionGroup>
  <Accordion title="Text Fields">
    * **Text** (default for strings)
    * **Date** with format selection
    * **DateTime** with timezone support
    * **Number** for numeric strings
    * **Decimal** for precise calculations
    * **Boolean** for true/false values
  </Accordion>

  <Accordion title="Number Fields">
    * **Number** (integer values)
    * **Decimal** (floating point, default for numbers)
  </Accordion>

  <Accordion title="Boolean Fields">
    * Automatically detected and mapped as boolean type
    * Handles true/false, 1/0, and yes/no variations
  </Accordion>
</AccordionGroup>

### Date Format Recognition

The system supports various date formats:

* ISO 8601 standard formats
* Common regional formats (MM/DD/YYYY, DD/MM/YYYY)
* Custom format specification
* Automatic timezone detection

## Working with JSON Data

### Simple JSON Objects

```json theme={null}
{
  "name": "John Doe",
  "age": 30,
  "active": true,
  "created_date": "2024-01-15T10:30:00Z"
}
```

Field types (Text, Number, Boolean, DateTime) are detected automatically from the structure.

### JSON Arrays

```json theme={null}
{
  "cars": [
    {
      "name": "Model Y",
      "year": 2024,
      "electric": true
    }
  ]
}
```

<Tip>
  Use **Repeat For Each** actions to iterate through JSON arrays. Configure the File Reader to parse the array, add the action, set the array field as the iteration source, then process items inside the loop.
</Tip>

## Using in Automations

Use the JSON File Reader in [automation workflows](/workflows/automation-system). Example flow:

```
API Response → JSON File Reader → Transform Data → Update Records → Generate Report
```

### Common Automation Patterns

<AccordionGroup>
  <Accordion title="API Data Processing">
    **Trigger**: API Request Action (JSON response)
    **File Reader**: Parse API response data
    **Actions**:

    * Transform Data to clean values
    * Create Record with parsed data
    * Update Record Fields with new information
    * Send Email Notification with results
  </Accordion>

  <Accordion title="Webhook Processing">
    **Trigger**: Webhook Received (JSON payload)
    **File Reader**: Extract webhook data
    **Actions**:

    * AI Classification to determine event type
    * Search Records to find related entries
    * Update Record Fields with webhook data
    * Post Comment with processing status
  </Accordion>

  <Accordion title="Configuration Processing">
    **Trigger**: File Upload (JSON config)
    **File Reader**: Parse configuration data
    **Actions**:

    * Transform Data to validate settings
    * Update Record Fields with configuration
    * Start Approval Process if required
    * Generate Report with config summary
  </Accordion>
</AccordionGroup>

### File Reader Actions

1. **Create Action** - Add a File Reader action to your automation
2. **Select Type** - Choose your configured JSON File Reader
3. **Configure Input** - Connect your JSON source
4. **Map Output** - Use the parsed fields in subsequent actions

## Best Practices

* **Data Validation** – Validate critical fields before processing to prevent automation failures
* **Consistent Structure** – Maintain consistent JSON structures across related automations for reliable processing
* **Type Accuracy** – Choose appropriate field types during configuration to ensure accurate data handling
* **Testing** – Test with sample data before deploying to production environments

## Advanced Features

### Nested Object Handling

The JSON File Reader handles complex nested structures:

```json theme={null}
{
  "user": {
    "profile": {
      "name": "John Doe",
      "preferences": {
        "theme": "dark",
        "notifications": true
      }
    }
  }
}
```

Access nested values using dot notation: `user.profile.name`.

For varying JSON structures, you can use **AI Classification** to determine structure type before **Dynamic Field Mapping** and the JSON File Reader, so parsing adapts to the data format.

## Error Handling and Troubleshooting

### Common Issues

<AccordionGroup>
  <Accordion title="Invalid JSON Format">
    **Symptoms**: JSON parsing fails with syntax errors

    **Causes**:

    * Missing brackets, quotes, or commas
    * Malformed JSON structure
    * Invalid characters in JSON

    **Solutions**:

    * Check for syntax errors using JSON validators
    * Verify JSON structure matches expected format
    * Use Transform Data to clean JSON before parsing
    * Implement IF conditions to handle malformed data
  </Accordion>

  <Accordion title="Missing Field Values">
    **Symptoms**: Expected fields return null or empty values

    **Causes**:

    * Field names don't match JSON keys (case-sensitive)
    * Optional fields missing in source JSON
    * Nested object path incorrect

    **Solutions**:

    * Verify field names match exactly (case-sensitive)
    * Use Branch actions to handle optional fields
    * Check nested object paths and dot notation
    * Add default values for missing fields
  </Accordion>

  <Accordion title="Type Conversion Errors">
    **Symptoms**: Data type mismatches in automation actions

    **Causes**:

    * Field types don't match JSON data types
    * String values expected as numbers
    * Date format not recognized

    **Solutions**:

    * Ensure field types match the actual data
    * Use Transform Data for type conversion
    * Configure date formats properly
    * Implement data validation steps
  </Accordion>
</AccordionGroup>

### Validation Strategies

<Info>
  Validate critical JSON fields (e.g., with Branch actions) before processing to ensure data quality and prevent automation failures.
</Info>

Use required-field checks, format validation (dates, numbers, emails), range checks for numbers, and pattern matching where the structure is predictable.

## Performance Optimization

* Map only the fields you need instead of parsing the full JSON.
* Use appropriate field types and process large payloads in batches when possible.
* For very large JSON, limit size or use streaming; clear variables after use.

## Comparison with Other File Readers

### When to Use JSON File Reader

Use the JSON File Reader for API responses, webhooks, configuration files, and other structured JSON. **Consider alternatives when**:

* Processing unstructured documents ([Text File Reader](/workflows/text-file-reader))
* Working with business forms ([Purchase Orders Reader](/workflows/purchase-orders-file-reader))
* Handling spreadsheet data ([Table File Reader](/workflows/table-file-reader))
* Requiring AI-powered analysis ([Elementum Intelligence Reader](/workflows/elementum-intelligence-file-reader))

## Next Steps

<CardGroup cols={2}>
  <Card title="Automation System" icon="gear" href="/workflows/automation-system">
    Learn how to integrate JSON File Readers with automation workflows
  </Card>

  <Card title="AI Services" icon="brain" href="/ai-agents/ai-services">
    Enhance JSON processing with AI classification and analysis
  </Card>

  <Card title="Table File Reader" icon="table" href="/workflows/table-file-reader">
    Process structured data from spreadsheets and CSV files
  </Card>

  <Card title="Elementum Intelligence Reader" icon="sparkles" href="/workflows/elementum-intelligence-file-reader">
    Upgrade to AI-powered document analysis for complex data extraction
  </Card>
</CardGroup>