Overview of JSON Pointer

1. Overview

In this tutorial, we’ll show how to use JSON Pointer to navigate and fetch information from JSON data.

We’ll also show how to perform operations such as inserting new data or updating existing key-values.

2. Dependency Setup

First, we need to add some dependencies to our pom.xml:

<dependency>
    <groupId>org.glassfish</groupId>
    <artifactId>javax.json</artifactId>
    <version>1.1.2</version>
</dependency>

3. JSON Pointer

JSON (“JavaScript Object Notation”) is a lightweight format for exchanging data between systems, originally specified by Douglas Crockford.

Although it uses JavaScript syntax, it’s language-independent, since the resultant is plain text.

JSON Pointer (RFC 6901) is a feature from JSON Processing 1.1 API (JSR 374). It defines a String that can be used for accessing values on a JSON document. It can be related to what XPath does for an XML document.

Through the use of JSON Pointer, we can fetch data from and alter a JSON file.

4. Accessing Data

We’ll see some examples of how to perform operations by implementing a class called JsonPointerCrud.

Let’s suppose we have a JSON file called books.json with the content:

{
    "library": "My Personal Library",
    "books": [
        { "title":"Title 1", "author":"Jane Doe" },
        { "title":"Title 2", "author":"John Doe" }
    ]
}

To access the data from that file, we need to read it and parse it to a JsonStructure. We can achieve it using Json.createReader() method, which accepts an InputStream or a FileReader.

Here’s how we can do that:

JsonReader reader = Json.createReader(new FileReader("books.json"));
JsonStructure jsonStructure = reader.read();
reader.close();

The content will be stored on a JsonStructure object. This is the object we’ll use to perform next operations.

4.1. Fetch Data from the File

To fetch a single value we create a JsonPointer, informing which tag we want to get the value from:

JsonPointer jsonPointer = Json.createPointer("/library");
JsonString jsonString = (JsonString) jsonPointer.getValue(jsonStructure);
System.out.println(jsonString.getString());

Note that the first character of this String is a ‘/’ – this is a syntactic requirement.

The result of this snippet is:

My Personal Library

To fetch a value from a list, we need to specify its index (where the first index is 0):

JsonPointer jsonPointer = Json.createPointer("/books/1");
JsonObject jsonObject = (JsonObject) jsonPointer.getValue(jsonStructure);
System.out.println(jsonObject.toString());

This outputs:

"title":"Title 2", "author":"John Doe"

4.2. Check if a Key is Present  in the File

Through the method containsValue, we can check if the value used to create the pointer is present on the JSON file:

JsonPointer jsonPointer = Json.createPointer("/library");
boolean found = jsonPointer.containsValue(jsonStructure);
System.out.println(found);

The result for this snippet is:

true

4.3. Insert New Key-Value

If we need to add a new value to the JSON, the createValue is the one to handle it. The method createValue is overloaded to accept String, int, long, double, BigDecimal and BigInteger:

JsonPointer jsonPointer = Json.createPointer("/total");
JsonNumber jsonNumber = Json.createValue(2);
jsonStructure = jsonPointer.add(jsonStructure, jsonNumber);
System.out.println(jsonStructure);

Again, our output is:

{
    "library": "My Personal Library",
    "total": 2,
    "books": [
        { "title":"Title 1", "author":"Jane Doe" },
        { "title":"Title 2", "author":"John Doe" }
    ]
}

4.4. Update a Key-Value

To update a value we need to create the new value first. After the value is created, we use the replace method from the pointer created using the key parameter:

JsonPointer jsonPointer = Json.createPointer("/total");
JsonNumber jsonNumberNewValue = Json.createValue(5);
jsonStructure = jsonPointer.replace(jsonStructure, jsonNumberNewValue);
System.out.println(jsonStructure);

Outputting:

{
    "library": "My Personal Library",
    "total": 5,
    "books": [
        { "title":"Title 1", "author":"Jane Doe" },
        { "title":"Title 2", "author":"John Doe" }
    ]
}

4.5. Remove a Key

To remove a key, we first create a pointer to the key. We then use the remove method:

JsonPointer jsonPointer = Json.createPointer("/library");
jsonPointer.getValue(jsonStructure);
jsonStructure = jsonPointer.remove(jsonStructure);
System.out.println(jsonStructure);

Resulting in:

{
    "total": 5,
    "books": [
        { "title":"Title 1", "author":"Jane Doe" },
        { "title":"Title 2", "author":"John Doe" }
    ]
}

4.6. Show the Full Content of the File

If the pointer is created with an empty String, the whole content is retrieved:

JsonPointer jsonPointer = Json.createPointer("");
JsonObject jsonObject = (JsonObject) jsonPointer.getValue(jsonStructure);
System.out.println(jsonObject.toString());

This code sample would output the whole contents of the jsonStructure.

5. Conclusion

In this quick article, we’ve covered how to work with JSON Pointer to perform various operations on JSON data.

And, as usual, the code related to this tutorial is over on GitHub.