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

# JSON Manipulation

> Parse, query, and transform JSON data

## Overview

The JSON tool provides operations for parsing, querying, validating, and transforming JSON data with JSONPath-like query support.

## json

Parse, query, and transform JSON data. Supports JSONPath-like queries for extracting values from complex structures.

**Input Parameters**

<ParamField path="operation" type="string" required>
  The JSON operation to perform. Must be one of: `parse`, `query`, `stringify`, `validate`
</ParamField>

<ParamField path="data" required>
  JSON input data. Pass a string for parse, or any JSON value (object, array, string, number, boolean, null) otherwise.
</ParamField>

<ParamField path="path" type="string">
  JSONPath-like path for query operation (e.g., `foo.bar[0].baz`)
</ParamField>

## Operations

### parse

Parse a JSON string into a structured value.

**Input**

<ParamField path="data" type="string" required>
  JSON string to parse
</ParamField>

**Output**

Returns the parsed JSON value (object, array, string, number, boolean, or null).

**Example**

```json theme={null}
{
  "operation": "parse",
  "data": "{\"name\": \"Alice\", \"age\": 30}"
}
```

**Response**

```json theme={null}
{
  "name": "Alice",
  "age": 30
}
```

**Error Conditions**

* `InvalidParameters`: `data` is not a string or contains invalid JSON

***

### stringify

Convert a JSON value to a pretty-printed string.

**Input**

<ParamField path="data" type="string" required>
  JSON string representing the value to stringify
</ParamField>

**Output**

Returns a JSON string (pretty-printed with indentation).

**Example**

```json theme={null}
{
  "operation": "stringify",
  "data": "{\"name\":\"Alice\",\"age\":30}"
}
```

**Response**

```json theme={null}
"{\n  \"name\": \"Alice\",\n  \"age\": 30\n}"
```

***

### query

Extract a value from JSON using a JSONPath-like path.

**Input**

<ParamField path="data" type="string" required>
  JSON string to query
</ParamField>

<ParamField path="path" type="string" required>
  Path to the value (e.g., `user.name`, `items[0].id`, `config.api.endpoints[2].url`)
</ParamField>

**Output**

Returns the value at the specified path.

**Example**

```json theme={null}
{
  "operation": "query",
  "data": "{\"user\": {\"name\": \"Alice\", \"emails\": [\"a@example.com\", \"b@example.com\"]}}",
  "path": "user.emails[0]"
}
```

**Response**

```json theme={null}
"a@example.com"
```

**Path Syntax**

* Dot notation for object fields: `foo.bar.baz`
* Array indexing with brackets: `items[0]`, `list[5]`
* Combined: `user.orders[2].items[0].name`

**Error Conditions**

* `InvalidParameters`: Missing `path` parameter or invalid array index
* `ExecutionFailed`: Field not found or array index out of bounds

***

### validate

Check if a string contains valid JSON.

**Input**

<ParamField path="data" type="string" required>
  String to validate as JSON
</ParamField>

**Output**

<ResponseField name="valid" type="boolean">
  True if string is valid JSON, false otherwise
</ResponseField>

**Example**

```json theme={null}
{
  "operation": "validate",
  "data": "{\"valid\": true}"
}
```

**Response**

```json theme={null}
{
  "valid": true
}
```

**Invalid JSON Example**

```json theme={null}
{
  "operation": "validate",
  "data": "{not valid json}"
}
```

**Response**

```json theme={null}
{
  "valid": false
}
```

## Examples

### Extract Nested Value

```json theme={null}
{
  "operation": "query",
  "data": "{\"config\": {\"database\": {\"host\": \"localhost\", \"port\": 5432}}}",
  "path": "config.database.host"
}
```

**Response:** `"localhost"`

### Access Array Element

```json theme={null}
{
  "operation": "query",
  "data": "{\"users\": [{\"name\": \"Alice\"}, {\"name\": \"Bob\"}]}",
  "path": "users[1].name"
}
```

**Response:** `"Bob"`

### Parse API Response

```json theme={null}
{
  "operation": "parse",
  "data": "{\"status\": 200, \"data\": {\"id\": 123, \"name\": \"Product\"}}"
}
```

**Response:**

```json theme={null}
{
  "status": 200,
  "data": {
    "id": 123,
    "name": "Product"
  }
}
```

### Format JSON

```json theme={null}
{
  "operation": "stringify",
  "data": "{\"compact\":true,\"version\":1}"
}
```

**Response:**

```json theme={null}
"{\n  \"compact\": true,\n  \"version\": 1\n}"
```

## Use Cases

### Extract Configuration Values

Parse config files and extract specific settings:

```json theme={null}
{
  "operation": "query",
  "data": "...",
  "path": "services.api.port"
}
```

### Validate External Data

Check if external input is valid JSON before processing:

```json theme={null}
{
  "operation": "validate",
  "data": "<user-input>"
}
```

### Navigate API Responses

Extract values from nested API responses:

```json theme={null}
{
  "operation": "query",
  "data": "<api-response>",
  "path": "data.results[0].id"
}
```

### Pretty Print JSON

Format compact JSON for readability:

```json theme={null}
{
  "operation": "stringify",
  "data": "{\"a\":1,\"b\":2}"
}
```

## Error Handling

<ResponseField name="InvalidParameters">
  * Unknown operation
  * `data` is not a string when required
  * Invalid JSON in `data` string
  * Missing `path` for query operation
  * Invalid array index in path
</ResponseField>

<ResponseField name="ExecutionFailed">
  * Field not found at specified path
  * Array index out of bounds
  * Failed to stringify JSON
</ResponseField>

## Technical Details

### Sanitization

No sanitization required - internal tool with no external data access.

### Approval

No approval required - safe internal operation.

### Path Resolution

Paths are resolved left-to-right:

1. Split on `.` to get segments
2. For each segment, check for array indexing `[n]`
3. Navigate to field, then to array index if present
4. Return final value

### OpenAI Compatibility

The `data` parameter is intentionally freeform (no `type` constraint) for OpenAI compatibility. OpenAI rejects union types containing `array` unless `items` is also specified.