reference/transforms/json_parser.md

---
last_modified_on: "2020-07-13"
component_title: "JSON Parser"
description: "The Vector `json_parser` transform accepts and outputs `log` events, allowing you to parse a log field value as JSON."
event_types: ["log"]
function_category: "parse"
issues_url: https://github.com/timberio/vector/issues?q=is%3Aopen+is%3Aissue+label%3A%22transform%3A+json_parser%22
operating_systems: ["Linux","MacOS","Windows"]
sidebar_label: "json_parser|[\"log\"]"
source_url: https://github.com/timberio/vector/tree/master/src/transforms/json_parser.rs
status: "prod-ready"
title: "JSON Parser Transform"
unsupported_operating_systems: []
---

import Fields from '@site/src/components/Fields';
import Field from '@site/src/components/Field';
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

The Vector `json_parser` transform
accepts and outputs [`log`][docs.data-model.log] events, allowing you to parse
a log field value as JSON.

<!--
     THIS FILE IS AUTOGENERATED!

     To make changes please edit the template located at:

     website/docs/reference/transforms/json_parser.md.erb
-->

## Configuration

<Tabs
  block={true}
  defaultValue="common"
  values={[{"label":"Common","value":"common"},{"label":"Advanced","value":"advanced"}]}>
<TabItem value="common">

```toml title="vector.toml"
[transforms.my_transform_id]
  type = "json_parser" # required
  inputs = ["my-source-or-transform-id"] # required
  drop_field = true # optional, default
  drop_invalid = true # required
  field = "message" # optional, default
```

</TabItem>
<TabItem value="advanced">

```toml title="vector.toml"
[transforms.my_transform_id]
  type = "json_parser" # required
  inputs = ["my-source-or-transform-id"] # required
  drop_field = true # optional, default
  drop_invalid = true # required
  field = "message" # optional, default
  overwrite_target = false # optional, default
  target_field = "root_field" # optional, no default
```

</TabItem>
</Tabs>

<Fields filters={true}>
<Field
  common={true}
  defaultValue={true}
  enumValues={null}
  examples={[true,false]}
  groups={[]}
  name={"drop_field"}
  path={null}
  relevantWhen={null}
  required={false}
  templateable={false}
  type={"bool"}
  unit={null}
  warnings={[]}
  >

### drop_field

If the specified [`field`](#field) should be dropped (removed) after parsing. If parsing
fails, the field will not be removed, irrespective of this setting.


</Field>
<Field
  common={true}
  defaultValue={null}
  enumValues={null}
  examples={[true]}
  groups={[]}
  name={"drop_invalid"}
  path={null}
  relevantWhen={null}
  required={true}
  templateable={false}
  type={"bool"}
  unit={null}
  warnings={[]}
  >

### drop_invalid

If `true` events with invalid JSON will be dropped, otherwise the event will be
kept and passed through.
 See [Invalid JSON](#invalid-json) for more info.


</Field>
<Field
  common={true}
  defaultValue={"message"}
  enumValues={null}
  examples={["message","parent.child","array[0]"]}
  groups={[]}
  name={"field"}
  path={null}
  relevantWhen={null}
  required={false}
  templateable={false}
  type={"string"}
  unit={null}
  warnings={[]}
  >

### field

The log field to decode as JSON. Must be a `string` value type.
 See [Field Notation Syntax](#field-notation-syntax) and [Invalid JSON](#invalid-json) for more info.


</Field>
<Field
  common={false}
  defaultValue={false}
  enumValues={null}
  examples={[false,true]}
  groups={[]}
  name={"overwrite_target"}
  path={null}
  relevantWhen={null}
  required={false}
  templateable={false}
  type={"bool"}
  unit={null}
  warnings={[]}
  >

### overwrite_target

If [`target_field`](#target_field) is set and the log contains a field of the same name as the
target, it will only be overwritten if this is set to `true`.


</Field>
<Field
  common={false}
  defaultValue={null}
  enumValues={null}
  examples={["root_field","parent.child"]}
  groups={[]}
  name={"target_field"}
  path={null}
  relevantWhen={null}
  required={false}
  templateable={false}
  type={"string"}
  unit={null}
  warnings={[]}
  >

### target_field

If this setting is present, the parsed JSON will be inserted into the log as a
sub-object with this name. If a field with the same name already exists, the
parser will fail and produce an error.
 See [Field Notation Syntax](#field-notation-syntax) for more info.


</Field>
</Fields>

## Examples

<Tabs
  block={true}
  defaultValue="simple"
  select={false}
  values={[{"label":"Simple","value":"simple"},{"label":"Wrapped","value":"wrapped"}]}>

<TabItem value="simple">

Given the following log event:

```javascript
{
  "message": "{"key": "value"}"
}
```

You can parse the JSON with:

```toml
[transforms.json]
  inputs = ["<source_id>"]
  type   = "json_parser"
  field  = "message"
```

This would produce the following event as output:

```javascript
{
  "key": "value"
}
```

By default, Vector drops fields after parsing them via the [`drop_field`](#drop_field)
option.

</TabItem>

<TabItem value="wrapped">

It is possible to chain `json_parser` transforms to effectively "unwrap"
nested JSON documents. For example, give this log event:

```javascript
{
  "message": "{"parent": "{"child": "value2"}"}"
}
```

You could unwrap the JSON with the following transforms:

```toml
[transforms.root_json]
  inputs = ["<source_id>"]
  type   = "json_parser"
  field  = "message"

[transforms.parent_json]
  inputs = ["root_json"]
  type   = "json_parser"
  field  = "parent"

[transforms.child_json]
  inputs = ["parent_json"]
  type   = "json_parser"
  field  = "child"
```

This would produce the following event as output:

```javascript
{
  "child": "value2"
}
```

By default, Vector drops fields after parsing them via the [`drop_field`](#drop_field)
option.

</TabItem>
</Tabs>

## How It Works

### Chaining / Unwrapping

Please see the [Examples section](#examples).

### Complex Processing

If you encounter limitations with the `json_parser`
transform then we recommend using a [runtime transform][urls.vector_programmable_transforms].
These transforms are designed for complex processing and give you the power of
full programming runtime.

### Environment Variables

Environment variables are supported through all of Vector's configuration.
Simply add `${MY_ENV_VAR}` in your Vector configuration file and the variable
will be replaced before being evaluated.

You can learn more in the
[Environment Variables][docs.configuration#environment-variables] section.

### Field Notation Syntax

The [`field`](#field) and [`target_field`](#target_field) options
support [Vector's field notation syntax][docs.reference.field-path-notation],
enabling access to root-level, nested, and array field values. For example:

```toml title="vector.toml"
[transforms.my_json_parser_transform_id]
  # ...
  field = "message"
  field = "parent.child"
  field = "array[0]"
  # ...
```

You can learn more about Vector's field notation in the
[field notation reference][docs.reference.field-path-notation].

### Invalid JSON

If the value for the specified [`field`](#field) is not valid JSON you can control keep
or discard the event with the [`drop_invalid`](#drop_invalid) option. Setting it to `true` will
discard the event and drop it entirely. Setting it to `false` will keep the
event and pass it through. Note that passing through the event could cause
problems and violate assumptions about the structure of your event.

### Merge Conflicts

#### Key conflicts

Any key present in the decoded JSON will override existin keys in the event.

#### Object conflicts

If the decoded JSON includes nested fields it will be _deep_ merged into the
event. For example, given the following event:

```javascript
{
  "message": "{\"parent\": {\"child2\": \"value2\"}}",
  "parent": {
    "child1": "value1"
  }
}
```

Parsing the `"message"` field would result the following structure:

```javascript
{
  "parent": {
    "child1": "value1",
    "child2": "value2"
  }
}
```

Notice that the `parent.child1` key was preserved.

[docs.configuration#environment-variables]: /docs/setup/configuration/#environment-variables
[docs.data-model.log]: /docs/about/data-model/log/
[docs.reference.field-path-notation]: /docs/reference/field-path-notation/
[urls.vector_programmable_transforms]: https://vector.dev/components/?functions%5B%5D=program