---
title: JSON Settings
slug: reference/json-settings
docTags: 
createdAt: 2025-09-10T15:01:50.617Z
---

The following collectors can be configured to read values from JSON:

- [MQTT collector](docId\:GgnQIJHlxIFoimBt-yP2C)
- [REST API collector](docId\:SyBXzdWWtNcPAi2HQdUsC) 

This page explains the settings that control how a JSON payload is parsed. The settings that are not specific to JSON are documented on the collector pages listed above.

## Collector JSON settings

### IgnoreJSONPathErrors

**Description:** The `IgnoreJSONPathErrors` setting determines whether errors in JSONPath expressions should be logged or not.

- Use `IgnoreJSONPathErrors = false` if your JSON structure should always contain specific fields, and you want to log missing or malformed JSONPath expressions.
- Use `IgnoreJSONPathErrors = true` if your JSON format is dynamic and you expect some fields to be missing. Errors resulting from missing paths or invalid expressions are ignored.

The setting does not cover `StatusPath`: an error there is always swallowed and the point falls back to status `Good`, whichever value you choose.

**Required**: No
**Default**: false

## Measurement JSON settings

The measurement settings reflect the configuration possibilities for mapping a JSON message. The values are extracted from the messages using JSONPath.
JSONPath documentation can be found in the [JSONPath specification](https://goessner.net/articles/JsonPath/), and [jsonpath.com](https://jsonpath.com) is a useful tool to test JSONPath expressions.

A path ending in `.*~` is a Factry extension: the suffix is stripped, the path is evaluated, and the keys of the resulting JSON object are extracted. Use it to read object keys rather than values.

The path expressions can either yield a single value, or a list of values. The expressions for the timestamp(s), status(es), and tags and values have to either yield the same amount of results as the expression for the Measurement(s), or only a single value, in which case that single value will be used for all found measurements.

### Topic

**Description**: The topic to listen to. When the topic is specified here, it will override the topic that was set in the collector. Only used by the MQTT collector.
**Required**: No

### MeasurementPath

**Description**: The json path that leads to a value, or a list of values in the message
**Required**: Yes

### TimestampPath

**Description**: The JSONPath that leads to a timestamp, or a list of timestamps in the message 
**Required**: No 
**If Empty**: The collector's timestamp will be assigned to data points.

### StatusPath

**Description**: The json path that leads to a status, or a list of statuses in the message. If not set, status will default to ‘Good’
**Required**: No

### TagNamesAndTagValuePaths

**Description**: Map describing tags, where keys are the tag names, and the values are the json paths of the tag values
**Required**: No

### TimestampLayout

**Description**: A timestamp layout is used to correctly interpret the resulting timestamp(s) from the TimestampPath. A list of available timestamp formats, along with their string representations, can be found in the [Golang Time package documentation](https://pkg.go.dev/time#Layout).
**Required**: No 
**If Empty**: The default RFC3339 timestamplayout e.g. `2006-01-02T15:04:05Z07:00` is used.

For timestamps in UNIX format, one of the following values can be used: UNIX (time in s), UNIXMILLIS (time in ms), UNIXMICROS (time in μs), or UNIXNANOS (time in ns).

For other timestamp formats, see the [examples](docId\:rkukKRD4aRiWfQk96lqy5) below.

:::hint{type="warning"}
Warning: The measurement `TimestampLayout` setting overrides the collector's `TimestampLayout` setting.
:::

**Timestamp Layout Examples**:

| Timestamp in JSON message | TimestampLayout           |
| ------------------------- | ------------------------- |
| 2024-03-31T14:30:00Z      | 2006-01-02T15:04:05Z07:00 |
| 2024-03-31T14:30:00+02:00 | 2006-01-02T15:04:05Z07:00 |
| 1711895400                | UNIX                      |
| 1711895400123             | UNIXMILLIS                |

**Custom Timestamp Layout Examples**:

| Timestamp in JSON message        | TimestampLayout                  |
| -------------------------------- | -------------------------------- |
| 31-03-2024 14:30:00.123          | 02-01-2006 15:04:05.000          |
| Sunday, 31 Mar 2024 14:30:00 UTC | Monday, 02 Jan 2006 15:04:05 MST |

Custom timestamp layouts allow flexibility for different timestamp representations. You can define them according to your needs using Go’s time layout reference [here](https://pkg.go.dev/time#Layout).

:::hint{type="info"}
**Important:** If your timestamps use a different structure, make sure to adjust the timestamp layout accordingly
:::

## Next steps

To learn how to read data from a JSON response using the JSON settings: see [Read data from JSON](docId\:rkukKRD4aRiWfQk96lqy5) .