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.

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

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.

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