jakartaee / jakartaee/jsonb-api

Specification should clarify the actual serialized format of Map<K,V>

Open
#287 12 comments 0 reactions 0 assignees View on GitHub
Dominant language
Java
Stars
95
Forks
41
Avg merge
1d 6h
Merged PRs (30d)
35

Description

Given JSON-B is serializing a `Map`, currently Yasson produces different serialized formats depending on `K`:
* (A) `K instanceof String`: Yasson produces `{"k.toString()":"serialize(v)"}`
* (B) otherwise: Yasson produces `[{"key":serialize(k),"value":serialize(v)}]`

In fact, it is rather unintuitive and not told anywhere in the spec that case (B) the marshaller introduces the string literals `key` and `value`, or that anything else but `String` keys will turn the map effectively into an *array*. Users of JSON-B cannot know this, but must have certainty and control over the actual output of *any* implementation, so a clarification is needed in the specification.

(1) Independent of the question whether this actually is the intended behavior, I request that the specification is amended by a clear wording *how* the serialized form MUST look like for which cases of `K`.

(2) In case the literals `key` and `value` are intended behavior, I request that the specification declares a way how the user of JSON-B can create output (A) for *non-String* `K` without writing a custom serializer and which *only* solves the `Map` case but does not chime in for non-maps.

Contributor guide

Open the contributing guide

Research direction

Locate the JSON-B specification section covering Map serialization and compare the documented behavior with the two formats described in the issue. Clarify the required output for String and non-String keys, including the key/value literals and whether users can request the object form; done means the specification states these rules and control points unambiguously.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.