JSON decomposition adapter

You can apply an adapter to your device to parse JSON data into Formant datapoints and ingest it directly.

For example, after applying the adapter, the following JSON data:

    "speed": 1,
    "heading" : {
        "x": 2,
        "y": 3

...would be decomposed and ingested as three separate datapoints:

Stream: "speed", Value: 1,
Stream: "heading.x", Value: 2,
Stream: "heading.y", Value: 3

When ingested, the name of the original JSON stream forms the basis of all converted stream names. For example, if the above JSON data was ingested on stream myJson, then the datapoints would be ingested with stream names myJson.speed, myJson.heading.x and myJson.heading.y.

Getting the adapter

Reach out to us to get the adapter. You can reach us via the Intercom messenger in the bottom-right corner of this page, or by sending an email to [email protected].


Once you've received the adapter, follow the instructions in Add an adapter to add it to your Formant organization and apply it to your device.


When you are adding the adapter, it is vital that the adapter is named Json Decomposition Adapter exactly.

If you want to give the adapter a different name in Formant, you'll have to modify the main.go file inside the provided zip file. You'll replace the name in the line: adapter.NewAdapterManager("Json Decomposition Adapter").


The adapter can ingest all valid JSON data. You can configure the adapter to read and interpret components of the JSON data in various ways through the configuration window.


Referencing JSON fields

Throughout the configuration of this adapter, you'll need to reference certain elements within your JSON data. For example, consider the following JSON data:


The value "baz" is given by foo.bar. For arrays, we add the index in brackets. So, array[0].value would return 10, and array[1] would return 3.

Stream list

This stream will be monitored for incoming JSON data, which will be flattened and ingested as shown above.

Whitelisting and blacklisting streams

You can whitelist (allowlist) or blacklist (blocklist) incoming data. A whitelist/allowlist takes precedence over a blacklist/blocklist; if both a whitelist and a blacklist are provided, the blacklist is ignored.

Wildcards are supported. For example, you could blacklist any stream that ends with "velocity" by adding "*velocity" to the blacklist.

Numeric sets

Numeric set ingestion requires the following arguments:

  • Labels Field
  • Values Field
  • Units Field
  • Ingestion Stream

Labels Field, Values Field, and Units Field all refer to their location in the JSON data. For example, in the following JSON data:

        "labels": ["velocity", "acceleration"],
        "values": [3, 4],
        "units": ["m/s", "m/s^2"],

...our configuration would look like this:

Labels Field: numericset.labels
Values Field: numericset.values
Units Field: numericset.units

Ingestion Stream is the stream which contains the numeric set data.


By default, incoming JSON data is ingested with the same timestamp at which that data was received. You can configure the JSON data to instead be associated with a timestamp contained within the JSON itself. To do so, provide the location within the JSON of the timestamp field, as well as the timestamp format.

Max array length

You can limit the number of possible elements ingested into Formant. This can help prevent accidental ingestion of huge amounts of data in the case of a mistaken array index reference.

This does not impact arrays that are part of a numeric set.


If you notice an issue with this page or need help, please reach out to us! Use the 'Did this page help you?' buttons below, or get in contact with our Customer Success team via the Intercom messenger in the bottom-right corner of this page, or at [email protected].