Add Jackson module to serialize/deserialize FieldValue

This commit adds a new `GraphQlModule` Jackson module that supports:

* serialization/deserialization of `FieldValue<T>`
* the upgrade of `FieldValue<T>` as reference types

This enables `FieldValue<T>` to be read/written from/to JSON with
Jackson on the client side. Note, on the server side this module is not
involved as the payload is deserialized as a `Map<String,Object>` and
values are bound as `FieldValue<T>` types directly.

Closes gh-1174

Signed-off-by: James Bodkin <[email protected]>
[[email protected]: apply code conventions, use FieldValue type]
Signed-off-by: Brian Clozel <[email protected]>

Author: James Bodkin

spring-graphql-docs/modules/ROOT/pages/client.adoc

@@ -393,6 +393,30 @@ include-code::UseInterceptor[tag=register,indent=0]
 
 
 
+[[client.argument-value]
+== Argument Value
+
+If you want to use `ArgumentValue` from a client or test, you can register the
+`GraphQLModule` in Jackson which can serialize/deserialize the value depending on
+the state.
+
+For example:
+
+[source,java,indent=0,subs="verbatim,quotes"]
+----
+    @Configuration
+    public class MyConfiguration {
+
+    	@Bean
+    	public GraphQLModule graphQLModule() {
+    		return new GraphQLModule();
+    	}
+
+    }
+----
+
+
+
 [[client.dgsgraphqlclient]]
 == DGS Codegen
 

spring-graphql/src/main/java/org/springframework/graphql/client/json/FieldValueDeserializer.java

@@ -0,0 +1,92 @@
+/*
+ * Copyright 2020-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.graphql.client.json;
+
+import java.io.Serial;
+import java.io.Serializable;
+
+import com.fasterxml.jackson.databind.DeserializationContext;
+import com.fasterxml.jackson.databind.JavaType;
+import com.fasterxml.jackson.databind.JsonDeserializer;
+import com.fasterxml.jackson.databind.JsonMappingException;
+import com.fasterxml.jackson.databind.deser.ValueInstantiator;
+import com.fasterxml.jackson.databind.deser.std.ReferenceTypeDeserializer;
+import com.fasterxml.jackson.databind.jsontype.TypeDeserializer;
+import com.fasterxml.jackson.databind.ser.std.ReferenceTypeSerializer;
+
+import org.springframework.graphql.FieldValue;
+import org.springframework.lang.Nullable;
+
+/**
+ * {@link ReferenceTypeSerializer} that deserializes JSON values as {@link FieldValue}:
+ * <ul>
+ *     <li>a {@link FieldValue#isEmpty() non empty FieldValue} when the JSON key is present and its value is not {@literal null}.
+ *     <li>an {@link FieldValue#isEmpty() empty FieldValue} when the JSON key is present and its value is {@literal null}.
+ *     <li>an {@link FieldValue#isOmitted() ommitted FieldValue} when the JSON key is not present.
+ * </ul>
+ * @author James Bodkin
+ */
+class FieldValueDeserializer extends ReferenceTypeDeserializer<FieldValue<?>> {
+
+	@Serial
+	private static final long serialVersionUID = 1L;
+
+	FieldValueDeserializer(final JavaType fullType, @Nullable final ValueInstantiator vi,
+					final TypeDeserializer typeDeser, final JsonDeserializer<?> deser) {
+
+		super(fullType, vi, typeDeser, deser);
+	}
+
+	@Override
+	protected ReferenceTypeDeserializer<FieldValue<?>> withResolved(final TypeDeserializer typeDeser,
+					final JsonDeserializer<?> valueDeser) {
+
+		return new FieldValueDeserializer(_fullType, _valueInstantiator, typeDeser, valueDeser);
+	}
+
+	@Override
+	public FieldValue<? extends Serializable> getNullValue(final DeserializationContext ctxt) throws JsonMappingException {
+		return FieldValue.ofNullable((Serializable) _valueDeserializer.getNullValue(ctxt));
+	}
+
+	@Override
+	public Object getEmptyValue(final DeserializationContext ctxt) throws JsonMappingException {
+		return getNullValue(ctxt);
+	}
+
+	@Override
+	public Object getAbsentValue(final DeserializationContext ctxt) {
+		return FieldValue.omitted();
+	}
+
+	@Override
+	public FieldValue<?> referenceValue(final Object contents) {
+		return FieldValue.ofNullable((Serializable) contents);
+	}
+
+	@Nullable
+	@Override
+	public Object getReferenced(final FieldValue<?> value) {
+		return value.value();
+	}
+
+	@Override
+	public FieldValue<?> updateReference(final FieldValue<?> value, final Object contents) {
+		return FieldValue.ofNullable((Serializable) contents);
+	}
+
+}

spring-graphql/src/main/java/org/springframework/graphql/client/json/FieldValueSerializer.java

@@ -0,0 +1,89 @@
+/*
+ * Copyright 2020-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.graphql.client.json;
+
+import java.io.Serial;
+
+import com.fasterxml.jackson.databind.BeanProperty;
+import com.fasterxml.jackson.databind.JsonSerializer;
+import com.fasterxml.jackson.databind.jsontype.TypeSerializer;
+import com.fasterxml.jackson.databind.ser.std.ReferenceTypeSerializer;
+import com.fasterxml.jackson.databind.type.ReferenceType;
+import com.fasterxml.jackson.databind.util.NameTransformer;
+
+import org.springframework.graphql.FieldValue;
+import org.springframework.lang.Nullable;
+
+/**
+ * {@link ReferenceTypeSerializer} that serializes {@link FieldValue} values as:
+ * <ul>
+ *     <li>the embedded value if it is present and not {@literal null}.
+ *     <li>{@literal null} if the embedded value is present and {@literal null}.
+ *     <li>an empty value if the embedded value is not present.
+ * </ul>
+ * @author James Bodkin
+ */
+class FieldValueSerializer extends ReferenceTypeSerializer<FieldValue<?>> {
+
+	@Serial
+	private static final long serialVersionUID = 1L;
+
+	FieldValueSerializer(final ReferenceType fullType, final boolean staticTyping,
+					@Nullable final TypeSerializer vts, final JsonSerializer<Object> ser) {
+
+		super(fullType, staticTyping, vts, ser);
+	}
+
+	protected FieldValueSerializer(final FieldValueSerializer base, final BeanProperty property,
+					final TypeSerializer vts, final JsonSerializer<?> valueSer,
+					final NameTransformer unwrapper, final Object suppressableValue,
+					final boolean suppressNulls) {
+
+		super(base, property, vts, valueSer, unwrapper, suppressableValue, suppressNulls);
+	}
+
+	@Override
+	protected ReferenceTypeSerializer<FieldValue<?>> withResolved(final BeanProperty prop, final TypeSerializer vts,
+					final JsonSerializer<?> valueSer, final NameTransformer unwrapper) {
+
+		return new FieldValueSerializer(this, prop, vts, valueSer, unwrapper, _suppressableValue, _suppressNulls);
+	}
+
+	@Override
+	public ReferenceTypeSerializer<FieldValue<?>> withContentInclusion(final Object suppressableValue, final boolean suppressNulls) {
+		return new FieldValueSerializer(this, _property, _valueTypeSerializer,
+				_valueSerializer, _unwrapper, suppressableValue, suppressNulls);
+	}
+
+	@Override
+	protected boolean _isValuePresent(final FieldValue<?> value) {
+		return !value.isOmitted();
+	}
+
+	@Nullable
+	@Override
+	protected Object _getReferenced(final FieldValue<?> value) {
+		return value.value();
+	}
+
+	@Nullable
+	@Override
+	protected Object _getReferencedIfPresent(final FieldValue<?> value) {
+		return value.value();
+	}
+
+}

spring-graphql/src/main/java/org/springframework/graphql/client/json/FieldValueTypeModifier.java

@@ -0,0 +1,48 @@
+/*
+ * Copyright 2020-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.graphql.client.json;
+
+import java.lang.reflect.Type;
+
+import com.fasterxml.jackson.databind.JavaType;
+import com.fasterxml.jackson.databind.type.ReferenceType;
+import com.fasterxml.jackson.databind.type.TypeBindings;
+import com.fasterxml.jackson.databind.type.TypeFactory;
+import com.fasterxml.jackson.databind.type.TypeModifier;
+
+import org.springframework.graphql.FieldValue;
+
+/**
+ * {@link TypeModifier} that upgrades {@link FieldValue} types to {@link ReferenceType}.
+ *
+ * @author James Bodkin
+ */
+class FieldValueTypeModifier extends TypeModifier {
+
+	@Override
+	public JavaType modifyType(final JavaType type, final Type jdkType, final TypeBindings context, final TypeFactory typeFactory) {
+		Class<?> raw = type.getRawClass();
+		if (!type.isReferenceType() && !type.isContainerType() && raw == FieldValue.class) {
+			JavaType refType = type.containedTypeOrUnknown(0);
+			return ReferenceType.upgradeFrom(type, refType);
+		}
+		else {
+			return type;
+		}
+	}
+
+}

spring-graphql/src/main/java/org/springframework/graphql/client/json/GraphQlDeserializers.java

@@ -0,0 +1,45 @@
+/*
+ * Copyright 2020-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.graphql.client.json;
+
+import com.fasterxml.jackson.databind.BeanDescription;
+import com.fasterxml.jackson.databind.DeserializationConfig;
+import com.fasterxml.jackson.databind.JsonDeserializer;
+import com.fasterxml.jackson.databind.deser.Deserializers;
+import com.fasterxml.jackson.databind.jsontype.TypeDeserializer;
+import com.fasterxml.jackson.databind.type.ReferenceType;
+
+import org.springframework.graphql.FieldValue;
+import org.springframework.lang.Nullable;
+
+class GraphQlDeserializers extends Deserializers.Base {
+
+	@Nullable
+	@Override
+	public JsonDeserializer<?> findReferenceDeserializer(final ReferenceType refType, final DeserializationConfig config,
+					final BeanDescription beanDesc, final TypeDeserializer contentTypeDeserializer,
+					final JsonDeserializer<?> contentDeserializer) {
+
+		if (refType.hasRawClass(FieldValue.class)) {
+			return new FieldValueDeserializer(refType, null, contentTypeDeserializer, contentDeserializer);
+		}
+		else {
+			return null;
+		}
+	}
+
+}

spring-graphql/src/main/java/org/springframework/graphql/client/json/GraphQlModule.java

@@ -0,0 +1,58 @@
+/*
+ * Copyright 2020-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.graphql.client.json;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+import com.fasterxml.jackson.core.Version;
+import com.fasterxml.jackson.databind.Module;
+import com.fasterxml.jackson.databind.type.ReferenceType;
+
+import org.springframework.graphql.FieldValue;
+
+/**
+ * {@link Module Jackson module} for JSON support in GraphQL clients.
+ * <p>This module ships with the following features:
+ * <ul>
+ *   <li>Manage {@link FieldValue} types as {@link ReferenceType}, similar to {@link java.util.Optional}
+ *   <li>Serializing and Deserializing values contained in {@link FieldValue} reference types
+ * </ul>
+ * @author James Bodkin
+ * @since 1.4.0
+ */
+public class GraphQlModule extends Module {
+
+	@Override
+	public String getModuleName() {
+		return GraphQlModule.class.getName();
+	}
+
+	@Override
+	public Version version() {
+		return Version.unknownVersion();
+	}
+
+	@Override
+	public void setupModule(final SetupContext context) {
+		context.addSerializers(new GraphQlSerializers());
+		context.addDeserializers(new GraphQlDeserializers());
+		context.addTypeModifier(new FieldValueTypeModifier());
+
+		context.configOverride(FieldValue.class)
+			.setInclude(JsonInclude.Value.empty().withValueInclusion(JsonInclude.Include.NON_ABSENT));
+	}
+
+}