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

Author: sri-adarsh-kumar

release-notes/CREDITS

@@ -229,6 +229,8 @@ Viktor Szathmáry (@phraktle)
  * Reported #5115: `@JsonUnwrapped` Record deserialization can't handle name collision
  (reported by Viktor S)
   [3.1.0]
+ * Reported #5716: `@JsonUnwrapped` properties moved to end in 3.1.0
+  [3.1.1]
 
 Lee Chan Won (@chanwonlee)
  * Implemented #5223: Java Records missing type information with `DefaultTyping.NON_FINAL`

release-notes/VERSION

@@ -15,6 +15,9 @@ Versions: 3.x (for earlier see VERSION-2.x)
 #5710: `ObjectWriter` transforms polymorphic types into a tree incompletely
  (reported by Brandon S)
  (fix by @cowtowncoder, w/ Claude code)
+#5716: `@JsonUnwrapped` properties moved to end in 3.1.0
+ (reported by Viktor S)
+ (fix by @cowtowncoder, w/ Claude code)
 
 3.1.0 (23-Feb-2026)
 

src/main/java/tools/jackson/databind/introspect/POJOPropertiesCollector.java

@@ -13,6 +13,7 @@
 import tools.jackson.databind.cfg.MapperConfig;
 import tools.jackson.databind.deser.impl.UnwrappedPropertyHandler;
 import tools.jackson.databind.util.ClassUtil;
+import tools.jackson.databind.util.NameTransformer;
 import tools.jackson.databind.util.RecordUtil;
 
 /**
@@ -1058,13 +1059,20 @@ private void _addCreatorParams(Map<String, POJOPropertyBuilder> props,
 
             // First: check "Unwrapped" unless explicit name
             if (!hasExplicit) {
-                var unwrapper = _annotationIntrospector.findUnwrappingNameTransformer(_config, param);
+                NameTransformer unwrapper = _annotationIntrospector.findUnwrappingNameTransformer(_config, param);
                 if (unwrapper != null) {
-                    // If unwrapping, can use regardless of name; we will use a placeholder name
-                    // anyway to try to avoid name conflicts.
-                    PropertyName name = UnwrappedPropertyHandler.creatorParamName(param.getIndex());
-                    final POJOPropertyBuilder prop = _property(props, name);
-                    prop.addCtor(param, name, false, true, false);
+                    // If unwrapping, use a placeholder name to avoid name conflicts during
+                    // deserialization. Store the (possibly field-renamed) implicit name as
+                    // the internal name so _sortProperties() can place this property at its
+                    // declaration position without re-invoking the annotation introspector.
+                    // [databind#5716]
+                    final PropertyName placeholder = UnwrappedPropertyHandler.creatorParamName(param.getIndex());
+                    final PropertyName internalName = hasImplicit ? implName : placeholder;
+                    final POJOPropertyBuilder prop = new POJOPropertyBuilder(_config,
+                            _annotationIntrospector, _forSerialization, internalName, placeholder);
+                    prop._unwrapped = true;
+                    props.put(placeholder.getSimpleName(), prop);
+                    prop.addCtor(param, placeholder, false, true, false);
                     creatorProps.add(prop);
                     continue;
                 }
@@ -1821,6 +1829,17 @@ protected void _sortProperties(Map<String, POJOPropertyBuilder> props)
                 // 16-Jan-2016, tatu: Related to [databind#1317], make sure not to accidentally
                 //    add back pruned creator properties!
 
+                // [databind#5716]: @JsonUnwrapped creator params use a placeholder name to avoid
+                // name conflicts during deserialization. The actual getter property name is stored
+                // as internalName in _addCreatorParams(), so use it here for correct ordering.
+                if (prop.isUnwrapped()) {
+                    String internalName = prop.getInternalName();
+                    POJOPropertyBuilder pb = all.get(internalName);
+                    if (pb != null) {
+                        ordered.put(internalName, pb);
+                        continue;
+                    }
+                }
                 String name = prop.getName();
                 // 27-Nov-2019, tatu: Not sure why, but we should NOT remove it from `all` tho:
 //                if (all.remove(name) != null) {

src/main/java/tools/jackson/databind/introspect/POJOPropertyBuilder.java

@@ -71,6 +71,17 @@ public class POJOPropertyBuilder
      */
     protected transient AnnotationIntrospector.ReferenceProperty _referenceInfo;
 
+    /**
+     * Flag that indicates this property is marked with {@code @JsonUnwrapped}.
+     * When set on a creator (constructor) parameter, the property uses a
+     * placeholder as its external name to avoid conflicts during deserialization,
+     * while {@link #_internalName} holds the actual implicit parameter name used
+     * for declaration-order sorting.
+     *
+     * @since 3.1.1
+     */
+    protected boolean _unwrapped;
+
     public POJOPropertyBuilder(MapperConfig<?> config, AnnotationIntrospector ai,
             boolean forSerialization, PropertyName internalName) {
         this(config, ai, forSerialization, internalName, internalName);
@@ -97,6 +108,7 @@ protected POJOPropertyBuilder(POJOPropertyBuilder src, PropertyName newName)
         _getters = src._getters;
         _setters = src._setters;
         _forSerialization = src._forSerialization;
+        _unwrapped = src._unwrapped;
     }
 
     /*
@@ -400,6 +412,13 @@ public boolean hasFieldAndNothingElse() {
     @Override
     public boolean hasConstructorParameter() { return _ctorParameters != null; }
 
+    /**
+     * Returns {@code true} if this property is marked with {@code @JsonUnwrapped}.
+     *
+     * @since 3.1
+     */
+    public boolean isUnwrapped() { return _unwrapped; }
+
     @Override
     public boolean couldDeserialize() {
         return (_ctorParameters != null)

src/test/java/tools/jackson/databind/records/RecordUnwrappedOrdering5716Test.java

@@ -0,0 +1,34 @@
+package tools.jackson.databind.records;
+
+import org.junit.jupiter.api.Test;
+
+import com.fasterxml.jackson.annotation.JsonUnwrapped;
+
+import tools.jackson.databind.MapperFeature;
+import tools.jackson.databind.ObjectMapper;
+import tools.jackson.databind.json.JsonMapper;
+import tools.jackson.databind.testutil.DatabindTestUtil;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+// [databind#5716] @JsonUnwrapped record properties should stay at declaration position
+public class RecordUnwrappedOrdering5716Test extends DatabindTestUtil
+{
+    record Name(String first, String last) { }
+    record Row(long time, @JsonUnwrapped Name name, double score) { }
+
+    private final ObjectMapper MAPPER = JsonMapper.builder()
+            .disable(MapperFeature.SORT_PROPERTIES_ALPHABETICALLY)
+            .enable(MapperFeature.SORT_CREATOR_PROPERTIES_FIRST)
+            .build();
+
+    @Test
+    void unwrappedRecordShouldKeepDeclarationOrder() throws Exception
+    {
+        Row input = new Row(1L, new Name("a", "b"), 2.5d);
+
+        String json = MAPPER.writeValueAsString(input);
+
+        assertEquals(a2q("{'time':1,'first':'a','last':'b','score':2.5}"), json);
+    }
+}

src/test/java/tools/jackson/databind/records/RecordWithJsonUnwrappedTest.java

@@ -76,7 +76,7 @@ void unwrappedPojoShouldRoundTrip() throws Exception
         input.a.a = 1;
         input.a.b = 2;
 
-        String      json   = MAPPER.writeValueAsString(input);
+        String json = MAPPER.writeValueAsString(input);
         BarPojo5115 output = MAPPER.readValue(json, BarPojo5115.class);
 
         assertEquals(4, output.c);