Convert JSON Object to JSON Array in Java

1. Overview

JSON (JavaScript Object Notation) is a lightweight, structured format used for data exchange. Modern software widely uses JSON for data exchange, configuration, and API communication. In Java, working with JSON often involves libraries like org.json, Jackson, or Gson. While converting a JSON object to a JSON array may seem straightforward, the correct approach depends on the input structure and the desired output format.

In this tutorial, we’ll demonstrate how to convert a JSON object to a JSON array using different libraries, with code examples and JUnit tests for validation.

2. Use Cases and Considerations

Converting a JSON object to a JSON array is a common requirement in applications that interact with REST APIs, data pipelines, or configuration files. This transformation often becomes necessary when data originally modeled as key-value pairs must be serialized, iterated over, or reformatted for compatibility with front-end frameworks or external systems. For example, APIs may expect an array of objects rather than a map, especially when rendering tabular data or processing form submissions.

Before choosing a conversion method, developers should assess whether they need only the values from the JSON object or both keys and values as distinct entities. We should also consider how to use the resulting JSON array. Whether for display, transmission, or further manipulation, as this directly impacts the choice of library and transformation strategy.

3. Approaches to Conversion

Let’s now walk through three different approaches for converting a JSON object into a JSON array. For each library, we’ll first build a method to encapsulate the logic and then verify its correctness using the respective Junit.

3.1. Using the org.json Library

The org.json library is simple, widely used, and already included in many Java projects. This library provides a minimal and straightforward API for working with JSON objects. It offers straightforward APIs for both JSONObject and JSONArray. Let’s create a few methods that handle both common scenarios:

JSONArray convertValuesToArray(JSONObject jsonObject) {
    return new JSONArray(jsonObject.toMap().values());
}

This method then extracts the values() collection and wraps it in a JSONArray, resulting in an array of values only.

Let’s now validate the method by passing a simple JSONObject and checking that all values appear in the JSONArray:

@Test
void givenFlatJSONObject_whenConvertValues_thenJSONArrayOfValues() {
    JSONObject jsonObject = new JSONObject();
    jsonObject.put("id", 1);
    jsonObject.put("name", "Alice");

    OrgJsonConverter converter = new OrgJsonConverter();
    JSONArray result = converter.convertValuesToArray(jsonObject);

    assertEquals(2, result.length());
    assertTrue(result.toList().contains("Alice"));
}

Next, we add another method that constructs a JSONArray where each element is a key-value pair represented as its own JSONObject:

JSONArray convertToEntryArray(JSONObject jsonObject) {
    JSONArray result = new JSONArray();
    for (String key : jsonObject.keySet()) {
        JSONObject entry = new JSONObject();
        entry.put("key", key);
        entry.put("value", jsonObject.get(key));
        result.put(entry);
    }
    return result;
}

This method iterates over each key in the JSONObject and creates a new JSONObject containing two fields, “key” and “value”.

In this test, we verify that each key-value pair is correctly converted into a JSONObject with key and value fields inside the resulting JSONArray.

@Test
void givenFlatJSONObject_whenConvertToEntryArray_thenJSONArrayOfObjects() {
    JSONObject jsonObject = new JSONObject();
    jsonObject.put("language", "Java");
    jsonObject.put("framework", "Spring");

    OrgJsonConverter converter = new OrgJsonConverter();
    JSONArray result = converter.convertToEntryArray(jsonObject);

    assertEquals(2, result.length());
    assertEquals("language", result.getJSONObject(0).get("key"));
}

3.2. Using Jackson with Custom Logic

Jackson is a multi-purpose Java library for processing JSON data. It provides greater control over JSON structures using its capabilities. Although Jackson primarily works with its tree model, we can still integrate it with JSONObject by converting it internally.

Let’s write a method that accepts a JSONObject, transforms it into Jackson’s internal model, and returns an ArrayNode:

ArrayNode convertToArray(JSONObject jsonObject) {
    ObjectMapper mapper = new ObjectMapper();
    JsonNode jsonNode = mapper.convertValue(jsonObject.toMap(), JsonNode.class);

    ArrayNode result = mapper.createArrayNode();
    jsonNode.fields().forEachRemaining(entry -> {
        ObjectNode obj = mapper.createObjectNode();
        obj.put("key", entry.getKey());
        obj.set("value", entry.getValue());
        result.add(obj);
    });

    return result;
}

We first convert the JSONObject to a Map and then use Jackson’s convertValue() to treat it as a JSONNode. From there, we loop over the fields and build an ArrayNode containing new key-value pairs. This method is powerful for more complex integrations.

Let’s test the Jackson-based method by converting a JSONObject with two key-value pairs and asserting that it structures them as individual key-value objects in the resulting ArrayNode:

@Test
void givenJSONObject_whenConvertToArray_thenArrayNodeOfKeyValueObjects() {
    JSONObject jsonObject = new JSONObject();
    jsonObject.put("country", "India");
    jsonObject.put("code", "IN");

    JacksonConverter converter = new JacksonConverter();
    ArrayNode result = converter.convertToArray(jsonObject);

    assertEquals(2, result.size());
    assertEquals("country", result.get(0).get("key").asText());
}

3.3. Using Gson With JSON Object

Gson is the next Java JSON library. It doesn’t accept JSON objects directly, but we can still use it by converting it to a map internally. Let’s build a method that creates a JsonArray from a JSONObject, where each element is a key-value pair:

JsonArray convertToKeyValueArray(JSONObject jsonObject) {
    JsonArray result = new JsonArray();
    jsonObject.keySet().forEach(key -> {
        JsonObject entry = new JsonObject();
        entry.addProperty("key", key);
        entry.add("value", com.google.gson.JsonParser.parseString(jsonObject.get(key).toString()));
        result.add(entry);
    });
    return result;
}

We iterate through the keys of the JSONObject and create a new JSONObject for each entry. Each new object holds the key and the parsed value. This approach works well with Gson APIs.

Here, we check if each entry in the JSONObject becomes a key-value object in the JsonArray:

@Test
void givenJSONObject_whenConvertToKeyValueArray_thenJsonArrayWithObjects() {
    JSONObject jsonObject = new JSONObject();
    jsonObject.put("brand", "Tesla");
    jsonObject.put("year", 2024);

    GsonConverter converter = new GsonConverter();
    JsonArray result = converter.convertToKeyValueArray(jsonObject);

    assertEquals(2, result.size());
    assertEquals("brand", result.get(0).getAsJsonObject().get("key").getAsString());
}

4. Conclusion

In this article, we explored ways to transform a JSON object to a JSON array using the most popular Java JSON libraries. The org.json library provides us with straightforward tools for both value-only and key-value pair conversions. Jackson excels when working with complex data models or integrating with other Jackson-based features. Gson provides a lightweight and clean way to achieve the same in Android or microservice environments.