Fix #512: Add @JsonWrapped annotation for grouping scalar fields into nested JSON objects by sri-adarsh-kumar · Pull Request #5715 · FasterXML/jackson-databind

sri-adarsh-kumar · 2026-02-26T18:52:32Z

Summary

Closes #512. Introduces @JsonWrapped, a field-level annotation that groups multiple scalar properties under a single named wrapper object in the serialized JSON and reads them back during deserialization.

PR to introduce annotation in FasterXML/jackson-annotations#346

Usage:

class Gene {
    public String symbol;

    @JsonWrapped("chr")
    @JsonProperty("id")
    public String chrId;

    @JsonWrapped("chr")
    public String chrName;
}
// → {"symbol":"TP53","chr":{"id":"17","chrName":"chr17"}}

What's in the MVP

Serialization (grouping scalar fields into a named nested object) and deserialization (reading from the wrapper object back into flat fields), with full support for @JsonProperty on inner fields, multiple wrapper groups, non-contiguous fields, @JsonPropertyOrder, enabled=false, and round-trip correctness. Validation rejects non-scalar types, empty wrapper names, name conflicts, and combined use with @JsonUnwrapped.

What's NOT in the MVP

@JsonView on inner wrapped fields is ignored — the wrapper always emits all its fields regardless of active view. Class-level @JsonFilter applies to the wrapper property itself (by wrapper name) but not to individual inner fields, and class-level @JsonInclude (e.g. NON_NULL) still applies to inner fields during serialization.

Please add the gen-ai label to this PR.

…o nested JSON objects Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

sri-adarsh-kumar · 2026-02-26T18:54:28Z

Submitting this for review.
Open for suggestions on what belongs or does not belong in the MVP.

github-actions · 2026-02-26T18:55:45Z

🧪 Code Coverage Report

Metric	Coverage	Change
Instructions	81.14%	📉 -0.060%
Branches	74.23%	📉 -0.060%

github-actions · 2026-02-26T18:55:50Z

🧪 Code Coverage Report

Metric	Coverage	Change
Instructions	81.14%	📉 -0.060%
Branches	74.23%	📉 -0.060%

cowtowncoder · 2026-02-27T03:33:49Z

@@ -0,0 +1,75 @@
+package tools.jackson.databind.annotation;


Since there's nothing databind-specific, this belongs in jackson-annotations, but for now can keep it here while considering rest of implementation.
(only annotations that depend on something in databind should be added within it)

@sri-adarsh-kumar Could you do a PR against https://github.com/FasterXML/jackson-annotations/ for this addition?

Created FasterXML/jackson-annotations#346

I think the build is failing for this PR as the SNAPSHOT version of jackson-annotations dependency does not yet contain the new annotation.

cowtowncoder · 2026-02-27T03:36:35Z

+ *   <li>The wrapper name ({@code value()}) must be non-empty.</li>
+ *   <li>The wrapper name must not conflict with an existing non-wrapped property on the same bean.</li>
+ *   <li>Not supported on {@code @JsonCreator} constructor or factory-method parameters.</li>
+ *   <li>MVP limitation: {@code @JsonView} on inner wrapped fields is ignored — the wrapper


Views are tricky here, understood.

cowtowncoder · 2026-02-27T03:40:25Z

+            Set<SettableBeanProperty> wrappedPropSet = new HashSet<>();
+            for (SettableBeanProperty prop : allProps) {
+                AnnotatedMember member = prop.getMember();
+                if (member == null) continue;


style: always use curly braces:

if (member == null) { continue; }

Changed.
Are there any format check plugins or equivalent for this repo?

Unfortunately no.

cowtowncoder · 2026-02-27T03:52:37Z


+    @Override
+    public String findWrappedGroupName(MapperConfig<?> config, AnnotatedMember member) {
+        String r = _primary.findWrappedGroupName(config, member);


This will not work properly with case of enabled = false, I think.

cowtowncoder · 2026-02-27T03:57:38Z

+     *
+     * @since 3.1
+     */
+    public static boolean isScalarType(JavaType type) {


I am not sure why we'd want to limit handling to scalar types, so probably need not comment on implementation.

github-actions · 2026-03-01T16:55:58Z

🧪 Code Coverage Report

Metric	Coverage	Change
Instructions	81.15%	📉 -0.060%
Branches	74.22%	📉 -0.080%

github-actions · 2026-03-01T17:48:05Z

🧪 Code Coverage Report

Metric	Coverage	Change
Instructions	81.16%	📉 -0.050%
Branches	74.21%	📉 -0.090%

github-actions · 2026-03-01T18:43:18Z

🧪 Code Coverage Report

Metric	Coverage	Change
Instructions	81.16%	📉 -0.050%
Branches	74.21%	📉 -0.090%

github-actions · 2026-03-01T19:00:24Z

🧪 Code Coverage Report

Metric	Coverage	Change
Instructions	81.15%	📉 -0.060%
Branches	74.25%	📉 -0.050%

…ntract and validation Cleaned up the @JsonWrapped annotation implementation to use a three-value return contract for the wrapper name: null (not present), empty string (explicitly disabled in mix-ins), or non-empty string (active wrapper). Removed the redundant 'enabled' flag and simplified validation logic in BeanDeserializerBase. Updated WrappedPropertyHandler method signatures. Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

…ections, maps, arrays Removes the scalar-only validation guards from BeanSerializerFactory and BeanDeserializerBase that blocked non-scalar types. The wrapper contract is unchanged — inner fields delegate to their own serializers/deserializers, so any Jackson-serializable type works without new machinery. Updates Javadoc, README, and converts former rejection tests to positive tests; adds serialization, deserialization, and round-trip coverage for POJO, List, Map, Array, mixed-type, and nested-wrapping scenarios. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

github-actions · 2026-03-01T19:04:26Z

🧪 Code Coverage Report

Metric	Coverage	Change
Instructions	81.15%	📉 -0.060%
Branches	74.25%	📉 -0.050%

github-actions · 2026-03-01T19:04:54Z

🧪 Code Coverage Report

Metric	Coverage	Change
Instructions	81.15%	📉 -0.060%
Branches	74.25%	📉 -0.050%

github-actions · 2026-03-01T22:31:05Z

🧪 Code Coverage Report

Metric	Coverage	Change
Instructions	81.16%	📉 -0.050%
Branches	74.25%	📉 -0.050%

github-actions · 2026-03-17T03:16:12Z

🧪 Code Coverage Report

Metric	Coverage	Change
Instructions	81.29%	📉 -0.050%
Branches	74.50%	📉 -0.050%

github-actions · 2026-03-23T22:31:19Z

🧪 Code Coverage Report

Metric	Coverage	Change
Instructions	81.30%	📉 -0.060%
Branches	74.56%	📉 -0.050%

github-actions · 2026-04-02T02:12:47Z

🧪 Code Coverage Report

Metric	Coverage	Change
Instructions	81.39%	📉 -0.050%
Branches	74.62%	📉 -0.050%

github-actions · 2026-04-18T22:50:15Z

🧪 Code Coverage Report

Metric	Coverage	Change
Instructions	81.51%	📉 -0.060%
Branches	74.81%	📉 -0.060%

sri-adarsh-kumar · 2026-04-21T11:31:28Z

@cowtowncoder Small Reminder.
Please let me know if you need any changes from my side.

github-actions · 2026-04-21T11:34:26Z

🧪 Code Coverage Report

Metric	Coverage	Change
Instructions	81.53%	📉 -0.050%
Branches	74.81%	📉 -0.060%

github-actions · 2026-04-24T04:15:18Z

🧪 Code Coverage Report

Metric	Coverage	Change
Instructions	81.50%	📉 -0.060%
Branches	74.80%	📉 -0.050%

github-actions · 2026-04-28T03:23:49Z

🧪 Code Coverage Report

Metric	Coverage	Change
Instructions	81.54%	📉 -0.060%
Branches	74.87%	📉 -0.060%

- Delete tools.jackson.databind.annotation.JsonWrapped (moved to com.fasterxml.jackson.annotation.JsonWrapped in jackson-annotations) - Update JacksonAnnotationIntrospector import to new package - Update imports in JsonWrapped{Serialization,Deserialization,Validation}Test - Fix README Javadoc link to point to jackson-annotations repo Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…adarsh-kumar/jackson-databind into feature/512-json-wrapped-annotation

Add `!ann.enabled()` check in `JacksonAnnotationIntrospector.findWrappedGroupName`, mirroring the identical pattern in `findUnwrappingNameTransformer` for `@JsonUnwrapped`. When `enabled=false`, the method now returns `null` so chained introspectors are unaffected — the empty-string sentinel remains the hard-disable mechanism. Also updates the `AnnotationIntrospector.findWrappedGroupName` Javadoc to document the `enabled=false` → null mapping, and adds three TDD tests covering the new behaviour via mix-in (serialization + deserialization) and direct annotation. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

cowtowncoder · 2026-05-04T17:59:15Z

Due to timing, unfortunately I think this needs to go in 3.3, not 3.2 -- I am trying to close up 3.2 and this results in significant internal changes.
But I will make sure to get this reviewed and merged ASAP after 3.2.0 release.
Similarly will defer jackson-annotations change to next version.

Thank you for all your work here @sri-adarsh-kumar .

sri-adarsh-kumar and others added 2 commits February 26, 2026 19:47

ISSUE-512: Add @JsonWrapped annotation for grouping scalar fields int…

bc7b5f9

…o nested JSON objects Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Merge branch '3.x' into feature/512-json-wrapped-annotation

93391ac

sri-adarsh-kumar marked this pull request as ready for review February 26, 2026 18:59