JsonbPropertyOrder annotation users guide

One of my coworkers recently informed me of what they believed was a JSON-B bug in Yasson where a class annotated with @JsonbPropertyOrder(PropertyOrderStrategy.LEXICOGRAPHICAL) did not observe a lexicographical ordering for properties.

My reply was that it was actually a user error because the value of @JsonbPropertyOrder is a list of property names in a desired order, not a PropertyOrderStrategy constant, despite the similarity in the names of the two classes. However, he came back to me with a contradictory section from the json-b.net user guide that backed up what he was attempting,

http://json-b.net/users-guide.html

which states that PropertyOrderStrategy can be set "using @JsonbPropertyOrder annotation on class". It even gives the following example of doing so,

@JsonbPropertyOrder(PropertyOrderStrategy.ANY) public class Person { private String name; private String profession; }

The JavaDoc for JsonbPropertyOrder very clearly indicates that the value is an "Array of property names which defines an order" and specifies the "Order in which properties are serialized. Names must correspond to original names defined in Java class before any customization applied", https://static.javadoc.io/javax.json.bind/javax.json.bind-api/1.0/javax/json/bind/annotation/JsonbPropertyOrder.html

So I would argue that the proper interpretation of @JsonbPropertyOrder(PropertyOrderStrategy.LEXICOGRAPHICAL) is that it would cause a property named "LEXICOGRAPHICAL" (the String value of the constant) to be ordered before all other properties, not that it would apply the PropertyOrderStrategy.LEXICOGRAPHICAL ordering strategy.

If others agree on this, can we get the user guide updated to avoid causing confusion? I'm unsure if the language/example in the user guide was just a mistake or if it was intentionally written that way due to a different understanding of the expected behavior.

I would propose changing the example and previous line as follows:

...

or by using @JsonbPropertyOrder to specify an explicit ordering of properties by name:

@JsonbPropertyOrder({ "profession", "name" }) public class Person { private String name; private String profession; }

Nathan Rauh

Software Engineer, WebSphere Application Server IBM Rochester Bldg 050-2 H215-1 3605 Highway 52N Rochester, MN 55901-7802

jansupol / jsonbapi

JsonbPropertyOrder annotation users guide #63