Deprecated

containsKey() is deprecated since ArduinoJson 7.2 and you must use is<T>() instead.

// Before
if (doc.containsKey("value")) {
  int value = doc["value"];
  // ...
}

// After
if (doc["value"].is<int>()) {
  int value = doc["value"];
  // ...
}

If you want to check that a key exists regardless of its type, you can use is<JsonVariant>().

Description

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

This function only works if the JsonVariant points to an object. It returns false if the JsonVariant is null, or if it points to an array.

This function can (and should) be avoided most of the time. See below.

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;
bool containsKey(std::string_view key) const;

Arguments

key: the key to look for.

Return value

JsonVariantConst::containsKey() returns a bool that tells whether the key was found or not:

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

Example

JsonDocument doc;
doc["location"]["city"] = "Paris";

JsonVariantConst location = doc["location"];
bool hasCity = location.containsKey("city"); // true
bool hasCountry = location.containsKey("country"); // false

Avoid this function when you can!

This function can (and should) be avoided most of the time.

Because ArduinoJson implements the Null Object Pattern, it is always safe to read the object: if the key doesn’t exist, it returns an empty value. For example:

JsonDocument doc;
doc["location"]["city"] = "Paris";

JsonVariantConst location = doc["location"];
if (location.containsKey("city")) {
  const char* city = location["city"];
  Serial.println(city);
}

Can be written like this:

JsonDocument doc;
doc["location"]["city"] = "Paris";

const char* city = doc["location"]["city"];
if (city)
  Serial.println(city);

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 = doc["response"]["error"]["description"];
if (error) {
  Serial.println(error);
  return;
}

See also