Description

JsonObject::containsKey() tests whether a key exists in the object pointed by the JsonObject.

If the JsonObject is null, this function returns false.

Signature

bool containsKey(const char* key) const;
bool containsKey(const String& key) const;
bool containsKey(const std::string& key) const;
bool containsKey(const __FlashStringHelper& key) const;

Arguments

key: the key to test.

Return value

JsonObject::containsKey() returns a bool that tells whether the hey was found or not:

  • true if the key is present in the object
  • false if the key is absent of the object

Example

StaticJsonDocument<256> doc;
JsonObject root = doc.to<JsonObject>();
root["city"] = "Paris";

bool hasCity = root.containsKey("city"); // true
bool hasCountry = root.containsKey("country"); // false

Avoid this function when you can!

Using this function is not strictly necessary and can be avoided most of the time. Indeed, since ArduinoJson implements the Null Object Pattern, it is always safe to read the object. If the key doesn’t exist, returns an empty value.

For example:

if (root.containsKey("error")) {
  const char* error = root["error"]
  Serial.println(error);
  return;
}

Can be written like this:

JsonVariant error = root["error"];
if (!error.isNull()) {
  Serial.println(error.as<char*>());
  return;
}

This can even be simplified further if the default value (0 or NULL) is not within the acceptable range:

const char* error = root["error"];
if (error) {
  Serial.println(error);
  return;
}

This version should lead to a smaller and faster code since it only does the lookup once.

How to test nested keys?

You cannot test the presence of nested keys with containsKey() but, as explained above, it’s safe to read the object anyway.

For example, when Weather Underground returns an error like:

{
  "response": {
    "version": "0.1",
    "termsofService": "http://www.wunderground.com/weather/api/d/terms.html",
    "features": {
      "conditions": 1
    },
    "error": {
      "type": "querynotfound",
      "description": "No cities match your search query"
    }
  }
}

You should not try to call containsKey("response"), containsKey("error") and containsKey("description"). Instead, just get the value and test if it’s NULL:

const char* error = root["response"]["error"]["description"];
if (error) {
  Serial.println(error);
  return;
}