serializeJsonPretty()

Description

Serializes the JsonDocument to create a prettified JSON document, i.e. a document with spaces and line-breaks between values.

If you want a “minified” JSON document, use serializeJson()

Signatures

size_t serializeJsonPretty(const JsonDocument& doc, char* output, size_t outputSize);  // see remark 1
size_t serializeJsonPretty(const JsonDocument& doc, char output[size]);                // see remark 1
size_t serializeJsonPretty(const JsonDocument& doc, Print& output);
size_t serializeJsonPretty(const JsonDocument& doc, String& output);       // see remark 2
size_t serializeJsonPretty(const JsonDocument& doc, std::string& output);  // see remark 2

template<typename Writer> // custom writer class (see below)
size_t serializeJsonPretty(const JsonDocument& doc, Writer& output);

➀ These overloads only add the zero-terminator if there is enough room in the buffer; this is the same caveat as strncpy().
Therefore, make sure that the buffer is large enough or check the return value.

➁ This function treats String and std::string as streams: it doesn’t replace the content but appends to the end.

The two first overloads support unsigned char as well.

Arguments

doc: the JsonDocument to serialize (in fact, you can also use a JsonArray, a JsonObject, or a JsonVariant)
output: the destination buffer where the result should be written
outputSize: the capacity of the destination buffer

Because output can be any implementation of Print, you can uses instances like Serial, EthernetClient, WifiClient…

Return value

The number of characters written.

Configuration

You can configure serializeJsonPretty() with the following settings:

ARDUINOJSON_ENABLE_NAN writes NaN instead of null,
ARDUINOJSON_ENABLE_INFINITY writes Infinity instead of null.
ARDIUNOJSON_TAB is the string used to indent the document (default is " ", i.e., two spaces)

How to view the JSON output?

When you pass a Stream to serializeJsonPretty(), it writes the JSON to the stream but doesn’t print anything to the serial port, which makes troubleshooting difficult.

If you want to see what serializeJsonPretty() writes, use WriteLoggingStream from the StreamUtils library. See the example below.

Performance

When you pass a Stream to serializeJsonPretty(), it sends the bytes one by one, which can be slow depending on the target stream. For example, if you send to a WiFiClient on an ESP8266, it will send a packet over the air for each byte, which is terribly slow and inefficient. To improve speed and efficiency, we must send fewer, larger packets.

To write the JSON document in chunks, you can use WriteBufferingStream from the StreamUtils library. See the example in serializeJson()

Custom writer

If none of the supported output types is suitable for you, you can implement a custom writer class. This class must implement two member functions, as shown below:

struct CustomWriter {
  // Writes one byte, returns the number of bytes written (0 or 1)
  size_t write(uint8_t c);
  // Writes several bytes, returns the number of bytes written
  size_t write(const uint8_t *buffer, size_t length);
};

Then, pass a reference to an instance of this class as the second argument of serializeJsonPretty().

Example

StaticJsonDocument<200> doc;
doc["hello"] = "world";
serializeJsonPretty(doc, Serial);

will write the following string to the serial output:

{
  "hello": "world"
}