FasterXML / FasterXML/jackson-annotations
Support binding POJO properties using JSON pointer
- Langage dominant
- Java
- Étoiles
- 1.1k
- Forks
- 342
- Merge moyen
- 8 h 53 min
- PR mergées (30 j)
- 2
Description
## 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.
Guide de contribution
Aucun guide de contribution indexé pour ce dépôt
Évaluation
Cette issue n'a pas encore été évaluée.