Summary
This PR proposes adding support for binding a POJO property directly to a nested JSON value using JSON Pointer syntax.
Currently, mapping a value from deeply nested JSON generally requires one of the following approaches:
- Defining intermediate/nested POJOs
- Mapping the response to
JsonNode
- Adding an unpacking setter or creator
- Implementing a custom deserializer
For consumers that only need a small subset of fields from a large or deeply nested JSON response, these approaches can introduce unnecessary model classes or custom mapping logic.
This proposal provides an explicit and lightweight mechanism for mapping such values directly to POJO properties.
Example
Given the following JSON:
{
"zys": "asas",
"mnp": {
"klj": 1
}
}
A consumer could bind the nested value directly:
public class Response {
@JsonProperty("zys")
private String zys;
@JsonPointer("/mnp/klj")
private Integer klj;
}
Deserialization would then work as expected:
Response response = mapper.readValue(json, Response.class);
assertEquals("asas", response.getZys());
assertEquals(1, response.getKlj());
Motivation
Jackson's existing @JsonProperty annotation represents a JSON property name, and this proposal intentionally preserves that behavior.
For example:
@JsonProperty("mnp.klj")
private Integer klj;
should continue to represent a literal JSON property named mnp.klj, rather than being interpreted as a path to a nested property.
Overloading @JsonProperty with path semantics could introduce ambiguity and potentially affect existing applications that legitimately use ., /, or similar characters in JSON property names.
Introducing an explicit JSON Pointer-based mechanism avoids changing the semantics of @JsonProperty while providing an unambiguous way to express nested property binding.
JSON Pointer is also preferable to introducing a custom dot-separated path syntax because it provides standardized path semantics and is already supported and understood by Jackson's tree model.
Use Case
This functionality is particularly useful when consuming external APIs that return large or deeply nested responses while the application only needs a small number of values.
For example:
{
"employee": {
"details": {
"department": {
"id": 123
}
}
}
}
Without direct nested-property binding, a consumer may need to introduce several intermediate DTOs solely to retrieve id.
With JSON Pointer-based binding, the consumer could instead declare:
@JsonPointer("/employee/details/department/id")
private Integer departmentId;
This keeps the application's model focused on the data it actually consumes and avoids introducing intermediate DTOs solely to represent the structure of the source JSON.
Compatibility
The proposed functionality is additive and does not modify the existing semantics of @JsonProperty.
Existing applications would therefore continue to treat property names containing characters such as . or / as literal property names.
For example:
@JsonProperty("employee/details/id")
private Integer id;
would continue to map a literal property named employee/details/id; it would not be interpreted as a JSON Pointer.
Only an explicitly declared JSON Pointer mapping would enable nested-property traversal.
Initial Scope
The initial implementation focuses on deserialization and direct binding of a value identified by a JSON Pointer to a POJO property.
The intention is to keep the first implementation narrowly scoped while allowing the API and behavior to evolve based on maintainer feedback.
Open Questions
A few design decisions are worth discussing:
- Should JSON Pointer-based binding support serialization as well as deserialization?
- How should a missing pointer target be handled?
- How should an explicit JSON
null value differ from a missing pointer target?
- Should the functionality be exposed through a new annotation such as
@JsonPointer, or should an existing Jackson annotation be extended?
- Should JSON Pointer binding be supported only on fields, or also on setters, constructor parameters, and record components?
- How should JSON Pointer-based properties interact with existing Jackson features such as creators, naming strategies, null handling, and required properties?
Contributions
I'm open to contribute, if this feature request is accepted to be incorporated in databind.
Summary
This PR proposes adding support for binding a POJO property directly to a nested JSON value using JSON Pointer syntax.
Currently, mapping a value from deeply nested JSON generally requires one of the following approaches:
JsonNodeFor consumers that only need a small subset of fields from a large or deeply nested JSON response, these approaches can introduce unnecessary model classes or custom mapping logic.
This proposal provides an explicit and lightweight mechanism for mapping such values directly to POJO properties.
Example
Given the following JSON:
A consumer could bind the nested value directly:
Deserialization would then work as expected:
Motivation
Jackson's existing
@JsonPropertyannotation represents a JSON property name, and this proposal intentionally preserves that behavior.For example:
should continue to represent a literal JSON property named
mnp.klj, rather than being interpreted as a path to a nested property.Overloading
@JsonPropertywith path semantics could introduce ambiguity and potentially affect existing applications that legitimately use.,/, or similar characters in JSON property names.Introducing an explicit JSON Pointer-based mechanism avoids changing the semantics of
@JsonPropertywhile providing an unambiguous way to express nested property binding.JSON Pointer is also preferable to introducing a custom dot-separated path syntax because it provides standardized path semantics and is already supported and understood by Jackson's tree model.
Use Case
This functionality is particularly useful when consuming external APIs that return large or deeply nested responses while the application only needs a small number of values.
For example:
Without direct nested-property binding, a consumer may need to introduce several intermediate DTOs solely to retrieve
id.With JSON Pointer-based binding, the consumer could instead declare:
This keeps the application's model focused on the data it actually consumes and avoids introducing intermediate DTOs solely to represent the structure of the source JSON.
Compatibility
The proposed functionality is additive and does not modify the existing semantics of
@JsonProperty.Existing applications would therefore continue to treat property names containing characters such as
.or/as literal property names.For example:
would continue to map a literal property named
employee/details/id; it would not be interpreted as a JSON Pointer.Only an explicitly declared JSON Pointer mapping would enable nested-property traversal.
Initial Scope
The initial implementation focuses on deserialization and direct binding of a value identified by a JSON Pointer to a POJO property.
The intention is to keep the first implementation narrowly scoped while allowing the API and behavior to evolve based on maintainer feedback.
Open Questions
A few design decisions are worth discussing:
nullvalue differ from a missing pointer target?@JsonPointer, or should an existing Jackson annotation be extended?Contributions
I'm open to contribute, if this feature request is accepted to be incorporated in databind.