Description

The function deserializeJson() parses a JSON input and puts the result in a JsonDocument.

This function behaves differently depending on the type of the input:

  • For a read-only input, it duplicates the strings in the input document. This duplication consumes additional space in the JsonDocument.
  • For a writeable input, it stores pointers to the strings in the input buffer. This is the zero-copy mode. In this mode, the JsonDocument can be smaller, but ArduinoJson needs to modify the input buffer to insert null-terminators and replace escaped characters. Because the JsonDocument stores pointers to the input buffer, you must ensure that this buffer remains in memory.

Prefer the first mode when the input comes from a Stream; prefer the second when the input is in a buffer.

If the input is a char*, ensure the input buffer stays in memory until the JsonDocument is destructed.

Signatures

// writable input => zero-copy
DeserializationError deserializeJson(JsonDocument& doc, char* input);
DeserializationError deserializeJson(JsonDocument& doc, char* input, size_t inputSize);

// read-only input => duplication
DeserializationError deserializeJson(JsonDocument& doc, const char* input);
DeserializationError deserializeJson(JsonDocument& doc, const char* input, size_t inputSize);
DeserializationError deserializeJson(JsonDocument& doc, const __FlashStringHelper* input);
DeserializationError deserializeJson(JsonDocument& doc, const __FlashStringHelper* input, size_t inputSize);
DeserializationError deserializeJson(JsonDocument& doc, const String& input);
DeserializationError deserializeJson(JsonDocument& doc, const std::string& input);
DeserializationError deserializeJson(JsonDocument& doc, Stream& input);
DeserializationError deserializeJson(JsonDocument& doc, std::istream& input);

// all overloads also accept an optional parameter of type DeserializationOption::NestingLimit (see below)

Arguments

doc: the JsonDocument that will store the memory representation of the JSON document.

input: the JSON document to parse:

  • const char* is a string in RAM, it should be zero-terminated
  • const __FlashStringHelper* is a Flash string, usually created with F()
  • Stream is Arduino’s I/O stream interface, implemented by:

inputSize: the maximum number of bytes to read from input

This function supports an optional argument of type DeserializationOption::NestingLimit to change the maximum number of nesting level that the parser will accept. See below for the details.

Return value

Returns a DeserializationError.

Nesting limit

The ArduinoJson’s parser contains a recursive function that is called each time an opening brace ({) or opening bracket ([) appears in the input. In other words, each object/array nesting level causes a recursive call.

This recursive call is a security risk because an attacker could craft a JSON input with many opening brackets to cause a stack overflow.

To protect against this security risk, ArduinoJson limits the number of nesting levels. The macro ARDUINOJSON_DEFAULT_NESTING_LIMIT sets the default value.

If your JSON input contains more nesting levels that allowed, you can pass an extra parameter of type DeserializationOption::NestingLimit to deserializeJson(). See the example below.

Configuration

deserializeJson() can be configured with the following settings:

Example

Read-only input

const char* json = "{\"hello\":\"world\"}";
StaticJsonDocument<200> doc;
deserializeJson(doc, json);
const char* world = doc["hello"];

Zero-copy mode

char json[] = "{\"hello\":\"world\"}";
StaticJsonDocument<200> doc;
deserializeJson(doc, json);
const char* world = doc["hello"];

Raise the nesting limit

char json[] = "[[[[[[[[[[[[[[[42]]]]]]]]]]]]]]]";
StaticJsonDocument<200> doc;
deserializeJson(doc, json, DeserializationOption::NestingLimit(15));;
int answer = doc[0][0][0][0][0][0][0][0][0][0][0][0][0][0][0];

See also