Course – LS (cat=JSON/Jackson)

Get started with Spring 5 and Spring Boot 2, through the Learn Spring course:


1. Introduction

In this tutorial, we'll dig into the specifics of getting values in JSONObject instances.

For the general introduction to JSON support in Java, please check the introduction to JSON-Java.

2. JSONObject Structure

JSONObject is a map-like structure. It keeps its data as a set of key-value pairs. While the keys are of the String type, the values may be of several types. Additionally, the value types may be primitive or compound. Primitives are String, Number, and Boolean types, or JSONObject.NULL object. Compounds are JSONObject and JSONArray types. Thus, JSON data may have arbitrary complexity and nesting.

Consequently, getting values in the nested structure requires more effort. From this point on, let's refer to the following JSON data of an imaginary employee:

  "name" : "Bob",
  "profession" : "Software engineer",
  "department" : "Research",
  "age" : 40,
  "family" : [
      "wife" : {
        "name" : "Alice",
        "profession" : "Doctor",
        "age" : 38
      "son" : {
        "name" : "Peter",
        "occupation" : "Schoolboy",
        "age" : 11
  "performance" : [
      "2020" : 4.5
      "2021" : 4.8

3. Getter Methods of JSONObject

First, let's see what getter API the JSONObject class provides. There are two groups of methods – the get() and opt() methods. The difference between the two groups is that the get() methods throw when the key is not found, while opt() methods don't throw and return null or a specific value depending on the method.

Furthermore, each group has one generic method and several specific methods with type casting. The generic method returns an Object instance, while the specific methods return an already casted instance. Let's get the “family” field of the JSON data using the generic get() method. We assume that the JSON data has been preliminarily loaded into the jsonObject variable, which is of JSONObject type:

    JSONArray family = (JSONArray) jsonObject.get("family");

We can do the same in a more readable way using the specific getter for JSONArray:

    JSONArray family = jsonObject.getJSONArray("family");

4. Getting Values Directly

In this approach, we fetch the values directly by getting each intermediate value on the path to the desired value. The code below shows how to get the name of the employee's son directly:

    JSONArray family = jsonObject.getJSONArray("family");
    JSONObject sonObject = family.getJSONObject(1);
    JSONObject sonData = sonObject.getJSONObject("son");
    String sonName = sonData.getString("name");
    Assertions.assertEquals(sonName, "Peter");

As we can see, the approach of getting values directly has limitations. First, we need to know the exact structure of the JSON data. Second, we need to know the data type of each value on the way to use the right getter methods of JSONObject.

Additionally, we need to add thorough checks in the code when the structure of the JSON data is dynamic. For example, for all the get() methods, we need to enclose the code in the try-catch blocks. Furthermore, for the opt() methods, we need to add null or specific value checks.

5. Getting Values Recursively

In contrast, the recursive approach of getting values in JSON data is flexible and less error-prone. We need to consider the nested structure of JSON data when implementing this approach.

First, when the value of a key is of JSONObject or JSONArray type, we need to propagate the recursive search down in that value. Second, when the key is found in the current recursive call, we need to add its mapped value to the returned result, regardless of whether the value is of a primitive type or not.

The methods below implement the recursive search:

    public List<String> getValuesInObject(JSONObject jsonObject, String key) {
        List<String> accumulatedValues = new ArrayList<>();
        for (String currentKey : jsonObject.keySet()) {
            Object value = jsonObject.get(currentKey);
            if (currentKey.equals(key)) {

            if (value instanceof JSONObject) {
                accumulatedValues.addAll(getValuesInObject((JSONObject) value, key));
            } else if (value instanceof JSONArray) {
                accumulatedValues.addAll(getValuesInArray((JSONArray) value, key));

        return accumulatedValues;

    public List<String> getValuesInArray(JSONArray jsonArray, String key) {
        List<String> accumulatedValues = new ArrayList<>();
        for (Object obj : jsonArray) {
            if (obj instanceof JSONArray) {
                accumulatedValues.addAll(getValuesInArray((JSONArray) obj, key));
            } else if (obj instanceof JSONObject) {
                accumulatedValues.addAll(getValuesInObject((JSONObject) obj, key));

        return accumulatedValues;

For the sake of simplicity, we provided two separate methods: one for the recursive search in a JSONObject and the other in a JSONArray instance. JSONObject is a map-like structure, while JSONArray is an array-like structure. Thus, iteration is different for them. So, having all the logic in a single method would complicate the code with type casts and if-else branches.

Finally, let's write the testing code for the getValuesInObject() method:

    public void getAllAssociatedValuesRecursively() {
        List<String> values = jsonObjectValueGetter.getValuesInObject(jsonObject, "son");
        Assertions.assertEquals(values.size(), 1);

        String sonString = values.get(0);

        values = jsonObjectValueGetter.getValuesInObject(jsonObject, "name");
        Assertions.assertEquals(values.size(), 3);

        Assertions.assertEquals(values.get(0), "Bob");
        Assertions.assertEquals(values.get(1), "Alice");
        Assertions.assertEquals(values.get(2), "Peter");

6. Conclusion

In this article, we've discussed getting values in the JSONObject. The complete code for the fragments used in this discussion can be found over on GitHub.

Course – LS (cat=JSON/Jackson)

Get started with Spring 5 and Spring Boot 2, through the Learn Spring course:

res – REST with Spring (eBook) (everywhere)
Comments are closed on this article!