ISSUE-512: Add @JsonWrapped annotation for grouping scalar fields into nested JSON objects

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: sri-adarsh-kumar

README.md

@@ -431,6 +431,37 @@ Note that use of a "creator method" (`@JsonCreator` with `@JsonProperty` annotat
 can mix and match properties from constructor/factory method with ones that
 are set via setters or directly using fields.
 
+### Annotations: wrapping properties
+
+`@JsonWrapped` groups one or more scalar fields into a synthetic nested JSON object — the inverse of `@JsonUnwrapped`.
+
+```java
+public class Gene {
+    public String name;
+
+    @JsonWrapped("chr") public String chromosome;
+    @JsonWrapped("chr") public int    position;
+}
+```
+
+Serializing a `Gene` instance produces:
+
+```json
+{
+  "name" : "BRCA1",
+  "chr" : {
+    "chromosome" : "17",
+    "position" : 43044295
+  }
+}
+```
+
+Deserialization is also supported: Jackson reads the nested `"chr"` object and maps its fields back to the annotated POJO fields (round-trip).
+
+Note: only scalar/primitive fields may be wrapped — annotating a collection, map, array, or nested POJO will cause a mapping error.
+
+See the [`@JsonWrapped` Javadoc](src/main/java/tools/jackson/databind/annotation/JsonWrapped.java) for the full list of constraints.
+
 ## Tutorial: fancier stuff, conversions
 
 One useful (but not very widely known) feature of Jackson is its ability

src/main/java/tools/jackson/databind/AnnotationIntrospector.java

@@ -511,6 +511,17 @@ public Object findTypeIdResolver(MapperConfig<?> config, Annotated ann) {
      */
     public NameTransformer findUnwrappingNameTransformer(MapperConfig<?> config, AnnotatedMember member) { return null; }
 
+    /**
+     * Method for finding the wrapped group name for a member annotated
+     * with {@code @JsonWrapped}. Returns the wrapper object name if the
+     * member should be wrapped, or {@code null} if not.
+     *
+     * @since 3.1
+     */
+    public String findWrappedGroupName(MapperConfig<?> config, AnnotatedMember member) {
+        return null;
+    }
+
     /**
      * Method called to check whether given property is marked to
      * be ignored. This is used to determine whether to ignore

src/main/java/tools/jackson/databind/annotation/JsonWrapped.java

@@ -0,0 +1,75 @@
+package tools.jackson.databind.annotation;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import com.fasterxml.jackson.annotation.JacksonAnnotation;
+
+/**
+ * Annotation that groups one or more scalar bean properties into a synthetic
+ * nested JSON object during serialization, and extracts them back during
+ * deserialization. This is the inverse of {@link com.fasterxml.jackson.annotation.JsonUnwrapped}.
+ *
+ * <p>Multiple fields annotated with the same {@code value()} are grouped into
+ * a single wrapper object. Inner property names follow Jackson's standard naming
+ * ({@code @JsonProperty} or default).
+ *
+ * <p>Example: given a POJO such as:
+ * <pre>
+ * public class Gene {
+ *     public String name;
+ *
+ *     &#64;JsonWrapped("chr")
+ *     public String chromosome;
+ *
+ *     &#64;JsonWrapped("chr")
+ *     public int position;
+ * }
+ * </pre>
+ * serialization produces:
+ * <pre>
+ * {
+ *   "name" : "BRCA1",
+ *   "chr" : {
+ *     "chromosome" : "17",
+ *     "position" : 43044295
+ *   }
+ * }
+ * </pre>
+ *
+ * <p>Constraints:
+ * <ul>
+ *   <li>Only scalar and primitive types are supported as wrapped fields
+ *       (containers, maps, arrays, and nested POJOs will cause a mapping error).</li>
+ *   <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
+ *       is always emitted and all inner fields are always included regardless of active view.</li>
+ *   <li>MVP limitation: class-level {@code @JsonFilter} still applies to the wrapper property
+ *       by its wrapper name (the whole wrapper can be suppressed if the filter excludes it),
+ *       but inner fields are not individually filtered.</li>
+ *   <li>MVP limitation: class-level {@code @JsonInclude} (e.g. {@code NON_NULL}) still applies
+ *       to inner wrapped fields during serialization.</li>
+ * </ul>
+ *
+ * @see com.fasterxml.jackson.annotation.JsonUnwrapped
+ * @since 3.1
+ */
+@Target({ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER})
+@Retention(RetentionPolicy.RUNTIME)
+@JacksonAnnotation
+public @interface JsonWrapped {
+    /**
+     * Single-level wrapper object name (e.g. "chr").
+     * Must be non-empty.
+     */
+    String value();
+
+    /**
+     * Allows conditional disabling of wrapping.
+     */
+    boolean enabled() default true;
+}

src/main/java/tools/jackson/databind/deser/bean/BeanDeserializer.java

@@ -590,8 +590,14 @@ public Object deserializeFromObject(JsonParser p, DeserializationContext ctxt) t
         }
         if (_nonStandardCreation) {
             if (_unwrappedPropertyHandler != null) {
+                if (_wrappedPropertyHandler != null) {
+                    return deserializeWithUnwrappedAndWrapped(p, ctxt);  // both present
+                }
                 return deserializeWithUnwrapped(p, ctxt);
             }
+            if (_wrappedPropertyHandler != null) {
+                return deserializeWithWrapped(p, ctxt);                  // only wrapped
+            }
             if (_externalTypeIdHandler != null) {
                 return deserializeWithExternalTypeId(p, ctxt);
             }
@@ -1357,6 +1363,107 @@ protected Object _deserializeWithExternalTypeId(JsonParser p, DeserializationCon
         return ext.complete(p, ctxt, bean);
     }
 
+    /**
+     * Deserialization method for beans that have {@code @JsonWrapped} properties.
+     * Similar to standard property-by-property deserialization, but recognizes
+     * wrapper field names and dispatches to WrappedPropertyHandler.
+     */
+    protected Object deserializeWithWrapped(JsonParser p, DeserializationContext ctxt)
+        throws JacksonException
+    {
+        if (_delegateDeserializer != null) {
+            return _valueInstantiator.createUsingDelegate(ctxt,
+                _delegateDeserializer.deserialize(p, ctxt));
+        }
+        if (_propertyBasedCreator != null) {
+            // For MVP, wrapped properties on creator params are rejected during resolve()
+            // so this shouldn't be reached with wrapped creator properties.
+            // Fall through to non-default creation.
+            return deserializeFromObjectUsingNonDefault(p, ctxt);
+        }
+        final Object bean = _valueInstantiator.createUsingDefault(ctxt);
+        p.assignCurrentValue(bean);
+
+        if (_injectables != null) {
+            injectValues(ctxt, bean);
+        }
+        final Class<?> activeView = _needViewProcesing ? ctxt.getActiveView() : null;
+
+        for (int ix = p.currentNameMatch(_propNameMatcher); ;
+                ix = p.nextNameMatch(_propNameMatcher)) {
+            if (ix >= 0) {
+                // Known regular property
+                p.nextToken();
+                SettableBeanProperty prop = _propsByIndex[ix];
+                if (activeView != null && !prop.visibleInView(activeView)) {
+                    p.skipChildren();
+                    continue;
+                }
+                try {
+                    prop.deserializeAndSet(p, ctxt, bean);
+                } catch (Exception e) {
+                    throw wrapAndThrow(e, bean, prop.getName(), ctxt);
+                }
+                continue;
+            }
+            if (ix == PropertyNameMatcher.MATCH_END_OBJECT) {
+                break;
+            }
+            if (ix == PropertyNameMatcher.MATCH_ODD_TOKEN) {
+                // error handling for odd tokens
+                return _handleUnexpectedWithin(p, ctxt, bean);
+            }
+            // MATCH_UNKNOWN_NAME — check if it's a wrapper name
+            String propName = p.currentName();
+            p.nextToken();
+
+            if (_wrappedPropertyHandler.hasWrapperName(propName)) {
+                _wrappedPropertyHandler.handleWrappedObject(p, ctxt, bean,
+                    propName, _anySetter);
+                continue;
+            }
+
+            // Standard unknown property handling
+            if (_ignorableProps != null && _ignorableProps.contains(propName)) {
+                handleIgnoredProperty(p, ctxt, bean, propName);
+                continue;
+            }
+            if (_anySetter != null) {
+                try {
+                    _anySetter.deserializeAndSet(p, ctxt, bean, propName);
+                } catch (Exception e) {
+                    throw wrapAndThrow(e, bean, propName, ctxt);
+                }
+                continue;
+            }
+            handleUnknownProperty(p, ctxt, bean, propName);
+        }
+        return bean;
+    }
+
+    /**
+     * Deserialization method for beans that have <em>both</em> {@code @JsonUnwrapped} and
+     * {@code @JsonWrapped} properties.
+     *
+     * <p><strong>MVP limitation:</strong> This method currently delegates entirely to
+     * {@link #deserializeWithWrapped}, which means {@code @JsonUnwrapped} properties are
+     * <em>silently ignored</em> — they are removed from {@code _beanProperties} during
+     * {@code resolve()} and {@code _unwrappedPropertyHandler} is never invoked here.
+     * A full implementation must interleave the unwrapped-property token-buffering logic
+     * from {@link #deserializeWithUnwrapped} with the inline wrapper dispatch logic from
+     * {@link #deserializeWithWrapped}.
+     *
+     * <p>TODO: Implement proper combined handling (post-MVP).
+     *
+     * @see #deserializeWithWrapped
+     * @see #deserializeWithUnwrapped
+     */
+    protected Object deserializeWithUnwrappedAndWrapped(JsonParser p, DeserializationContext ctxt)
+        throws JacksonException
+    {
+        return deserializeWithWrapped(p, ctxt);
+    }
+
     @SuppressWarnings("resource")
     protected Object deserializeUsingPropertyBasedWithExternalTypeId(JsonParser p, DeserializationContext ctxt)
         throws JacksonException

src/main/java/tools/jackson/databind/deser/bean/BeanDeserializerBase.java

@@ -182,6 +182,13 @@ public abstract class BeanDeserializerBase
      */
     protected UnwrappedPropertyHandler _unwrappedPropertyHandler;
 
+    /**
+     * Handler for properties annotated with {@code @JsonWrapped}, if any.
+     *
+     * @since 3.1
+     */
+    protected WrappedPropertyHandler _wrappedPropertyHandler;
+
     /**
      * Handler that we need if any of properties uses external
      * type id.
@@ -284,6 +291,7 @@ protected BeanDeserializerBase(BeanDeserializerBase src, boolean ignoreAllUnknow
 
         _nonStandardCreation = src._nonStandardCreation;
         _unwrappedPropertyHandler = src._unwrappedPropertyHandler;
+        _wrappedPropertyHandler = src._wrappedPropertyHandler;
         _needViewProcesing = src._needViewProcesing;
         _serializationShape = src._serializationShape;
 
@@ -350,6 +358,7 @@ protected BeanDeserializerBase(BeanDeserializerBase src, ObjectIdReader oir)
 
         _nonStandardCreation = src._nonStandardCreation;
         _unwrappedPropertyHandler = src._unwrappedPropertyHandler;
+        _wrappedPropertyHandler = src._wrappedPropertyHandler;
         _needViewProcesing = src._needViewProcesing;
         _serializationShape = src._serializationShape;
 
@@ -394,6 +403,7 @@ public BeanDeserializerBase(BeanDeserializerBase src,
 
         _nonStandardCreation = src._nonStandardCreation;
         _unwrappedPropertyHandler = src._unwrappedPropertyHandler;
+        _wrappedPropertyHandler = src._wrappedPropertyHandler;
         _needViewProcesing = src._needViewProcesing;
         _serializationShape = src._serializationShape;
 
@@ -428,6 +438,7 @@ protected BeanDeserializerBase(BeanDeserializerBase src, BeanPropertyMap beanPro
 
         _nonStandardCreation = src._nonStandardCreation;
         _unwrappedPropertyHandler = src._unwrappedPropertyHandler;
+        _wrappedPropertyHandler = src._wrappedPropertyHandler;
         _needViewProcesing = src._needViewProcesing;
         _serializationShape = src._serializationShape;
 
@@ -642,6 +653,87 @@ public void resolve(DeserializationContext ctxt)
         } else {
             _unwrappedPropertyHandler = null;
         }
+
+        // Detect @JsonWrapped properties
+        WrappedPropertyHandler wrapped = null;
+        AnnotationIntrospector intr = ctxt.getAnnotationIntrospector();
+        if (intr != null) {
+            // Iterate a copy since we'll modify _beanProperties
+            List<SettableBeanProperty> allProps = new ArrayList<>();
+            for (SettableBeanProperty prop : _beanProperties) {
+                allProps.add(prop);
+            }
+
+            // First pass: collect wrapped properties and validate
+            Map<String, List<SettableBeanProperty>> groups = new LinkedHashMap<>();
+            Set<SettableBeanProperty> wrappedPropSet = new HashSet<>();
+            for (SettableBeanProperty prop : allProps) {
+                AnnotatedMember member = prop.getMember();
+                if (member == null) continue;
+                String wrapperName = intr.findWrappedGroupName(ctxt.getConfig(), member);
+                if (wrapperName == null) continue;
+                wrappedPropSet.add(prop);
+
+                // Validate: empty name
+                if (wrapperName.isEmpty()) {
+                    ctxt.reportBadDefinition(handledType(),
+                        String.format("@JsonWrapped value must not be empty (on property '%s')",
+                            prop.getName()));
+                }
+
+                // Validate: creator parameter
+                if ((prop instanceof CreatorProperty) && ((CreatorProperty) prop).getCreatorIndex() >= 0) {
+                    ctxt.reportBadDefinition(handledType(),
+                        String.format("@JsonWrapped on creator parameter '%s' is not supported",
+                            prop.getName()));
+                }
+
+                // Validate: scalar-only (symmetry with serialization)
+                JavaType type = prop.getType();
+                if (!_isScalarType(type)) {
+                    ctxt.reportBadDefinition(handledType(),
+                        String.format("@JsonWrapped is only supported on scalar/primitive types; "
+                            + "found %s on property '%s'",
+                            type.toCanonical(), prop.getName()));
+                }
+
+                groups.computeIfAbsent(wrapperName, k -> new ArrayList<>()).add(prop);
+            }
+
+            if (!groups.isEmpty()) {
+                // Validate: name conflicts (wrapper name vs non-wrapped property name)
+                Set<String> wrapperNames = groups.keySet();
+                for (SettableBeanProperty prop : allProps) {
+                    if (wrappedPropSet.contains(prop)) continue;  // this is a wrapped property, skip
+                    if (wrapperNames.contains(prop.getName())) {
+                        ctxt.reportBadDefinition(handledType(),
+                            String.format("Wrapper name '%s' conflicts with existing property '%s'",
+                                prop.getName(), prop.getName()));
+                    }
+                }
+
+                // Build handler and remove wrapped properties from bean properties
+                wrapped = new WrappedPropertyHandler();
+                for (Map.Entry<String, List<SettableBeanProperty>> entry : groups.entrySet()) {
+                    for (SettableBeanProperty prop : entry.getValue()) {
+                        wrapped.addProperty(entry.getKey(), prop);
+                        _beanProperties.remove(prop);
+                    }
+                }
+            }
+        }
+
+        if (wrapped != null) {
+            if (_unwrappedPropertyHandler != null) {
+                ctxt.reportBadDefinition(handledType(),
+                    String.format("Cannot use both @JsonWrapped and @JsonUnwrapped on the same bean '%s': "
+                        + "combined deserialization is not supported (post-MVP limitation). "
+                        + "Use one or the other.", ClassUtil.classNameOf(handledType())));
+            }
+            _wrappedPropertyHandler = wrapped;
+            _nonStandardCreation = true;
+        }
+
         // may need to disable vanilla processing, if unwrapped handling was enabled...
         _vanillaProcessing = _vanillaProcessing && !_nonStandardCreation;
     }
@@ -1976,4 +2068,8 @@ protected Object wrapInstantiationProblem(DeserializationContext ctxt,Throwable
         }
         return ctxt.handleInstantiationProblem(_beanType.getRawClass(), null, t);
     }
+
+    protected boolean _isScalarType(JavaType type) {
+        return BeanUtil.isScalarType(type);
+    }
 }