Skip to content

@JsonValue has lower precedence than module Serializers for container and container-like types #6341

Open

Description

@cowtowncoder

Summary

For container types (Collection, Map, and their -like variants), @JsonValue is consulted only after module-provided Serializers (findCollectionSerializer(), findMapSerializer(), findCollectionLikeSerializer(), findMapLikeSerializer()). For non-container types, @JsonValue is not overridden this way, so the behavior is inconsistent. A module serializer that handles a container type therefore silently pre-empts @JsonValue unless the module author remembers to check for it.

Where

BasicSerializerFactory.buildCollectionSerializer() (and the Map / MapLike / CollectionLike equivalents) documents the order:

// Order of lookups:
// 1. Custom serializers
// 2. Annotations (@JsonValue, @JsonDeserialize)
// 3. Defaults
for (Serializers serializers : customSerializers()) {       // (1) Custom
    ser = serializers.findCollectionSerializer(...);
    if (ser != null) break;
}
if (ser == null) {
    ser = findSerializerByAnnotations(ctxt, type, beanDescRef);   // (2) @JsonValue
    ...

BeanSerializerFactory._createSerializer2() sends every type.isContainerType() straight to buildContainerSerializer(), so nothing checks @JsonValue earlier. The same applies to @JsonFormat(shape = POJO), which is also checked only after custom serializers.

How it showed up

In jackson-datatypes-collections (Guava module, 3.3 branch) we added a serializer registered via Serializers.findCollectionSerializer() for Guava Multisets. A ForwardingMultiset subclass with a @JsonValue method serializes as "bag:1" without the module's serializer, but as [{"element":"a","count":1}] with it. A subclass annotated with @JsonFormat(shape = POJO) likewise loses its POJO output.

Expected

Either:

  1. @JsonValue (and POJO shape) take precedence over custom container serializers, consistent with non-container types; or
  2. keep the order, but document it clearly in the Serializers Javadoc (findCollectionSerializer() etc.): implementations are expected to return null for types that have @JsonValue, and say how to check that cheaply.

Workaround

In the module's findCollectionSerializer(), return null when beanDescRef.get().findJsonValueAccessor() != null or when formatOverrides.getShape() == POJO.

Notes

Changing the order (option 1) could break modules that rely on pre-empting. A narrower variant is to change it only for types where the user class has an explicit @JsonValue. The source reading above is from 3.3.0-SNAPSHOT; I have not checked earlier branches.

Activity

  1. changed the title [-]@JsonValue has lower precedence than module Serializers for container and container-like types[/-] [+]`@JsonValue` has lower precedence than module Serializers for container and container-like types[/+] on Oct 31, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions