Master JSON Pointer with Jackson: Syntax, Examples, and Java Code

1. Syntax

JSON Pointer is a Unicode string containing zero or more reference tokens, each prefixed by "/". If a token contains "~" or "/" they must be encoded as "~0" and "~1". Its ABNF syntax is:

json-pointer = *( "/" reference-token )
reference-token = *( unescaped / escaped )
unescaped = %x00-2E / %x30-7D / %x7F-10FFFF
escaped = "~" ( "0" / "1" )

If a JSON Pointer value does not conform to this syntax, it is considered an error condition.

2. Syntax Examples

All quotation marks ("), backslashes (\\) and control characters (0x00-1F) in a JSON Pointer must be escaped. For example, given the following JSON document:

{
  "foo": ["bar", "baz"],
  "": 0,
  "a/b": 1,
  "c%d": 2,
  "e^f": 3,
  "g|h": 4,
  "i\\j": 5,
  "k\"l": 6,
  " ": 7,
  "m~n": 8
}

The corresponding JSON Pointer strings and their values are:

""          // whole document
"/foo"      ["bar","baz"]
"/foo/0"    "bar" // first element of the array
"/"         0
"/a~1b"     1
"/c%d"      2
"/e^f"      3
"/g|h"      4
"/i\\j"     5
"/k\"l"     6
"/ "        7
"/m~0n"     8

3. Complex JSON Example

Example JSON (excerpt from the author's Juejin profile):

{
    "err_no": 0,
    "err_msg": "success",
    "data": {
        "user_name": "如梦技术",
        "description": "生活不止眼前的苟且，还有诗和远方的田野。",
        "blog_address": "https://www.dreamlu.net",
        "user_growth_info": {
            "user_id": 1591748566975837,
            "jpower": 4056,
            "jscore": 1208.1,
            "jpower_level": 4,
            "jscore_level": 5,
            "jscore_title": "先锋掘友",
            "author_achievement_list": [],
            "vip_level": 1,
            "vip_title": "初学乍练",
            "jscore_next_level_score": 2000,
            "jscore_this_level_mini_score": 500,
            "vip_score": 0
        }
    }
}

To retrieve the jscore_title field, the full JSON Pointer is /data/user_growth_info/jscore_title. Using JsonUtil (a comprehensive Jackson helper) the Java code is:

// read json as JsonNode
JsonNode jsonNode = JsonUtil.readTree(json);
// call at method with JSON Pointer
JsonNode titleNode = jsonNode.at("/data/user_growth_info/jscore_title");
// read node text
String jsCoreTitle = titleNode.asText();
System.out.println(jsCoreTitle); // 先锋掘友

When a JSON Pointer points to a non‑existent node, Jackson returns null for asText, asInt, etc., without throwing an error. Nodes can also be converted to Java beans, for example the user_growth_info node:

@Data
public class UserGrowthInfo {
    @JsonProperty("user_id")
    private Long userId;
    @JsonProperty("jpower")
    private Integer jpower;
    @JsonProperty("jscore")
    private Double jscore;
    @JsonProperty("jpower_level")
    private Integer jpowerLevel;
    @JsonProperty("jscore_level")
    private Integer jscoreLevel;
    @JsonProperty("jscore_title")
    private String jscoreTitle;
    @JsonProperty("author_achievement_list")
    private List<?> authorAchievementList;
    @JsonProperty("vip_level")
    private Integer vipLevel;
    @JsonProperty("vip_title")
    private String vipTitle;
    @JsonProperty("jscore_next_level_score")
    private Integer jscoreNextLevelScore;
    @JsonProperty("jscore_this_level_mini_score")
    private Integer jscoreThisLevelMiniScore;
    @JsonProperty("vip_score")
    private Integer vipScore;
}

Reading the JSON and converting to UserGrowthInfo bean:

// read json as JsonNode
JsonNode jsonNode = JsonUtil.readTree(json);
// read user_growth_info node
JsonNode userGrowthInfoNode = jsonNode.at("/data/user_growth_info");
// convert to bean
UserGrowthInfo userGrowthInfo = JsonUtil.treeToValue(userGrowthInfoNode, UserGrowthInfo.class);
System.out.println(userGrowthInfo);
// Output: UserGrowthInfo(userId=1591748566975837, jpower=4056, jscore=1208.1, jpowerLevel=4, jscoreLevel=5, jscoreTitle=先锋掘友, authorAchievementList=[], vipLevel=1, vipTitle=初学乍练, jscoreNextLevelScore=2000, jscoreThisLevelMiniScore=500, vipScore=0)

4. Summary

Jackson JSON Pointer syntax is simple and powerful; although the official documentation has been reorganized, this guide provides practical examples and Java code to help developers extract data efficiently, including usage within the mica framework and HTTP requests.