Allow jsonschema2pojo custom keywords to use x- prefix (e.g. javaType can be x-javaType)

[dunivlorraine]

Hi!

I use jsonschema2pojo along with its Maven extension to automatically generate Java classes from JSON Schemas. These schemas are registered in a Kafka Schema Registry, which strictly follows the JSON Schema specifications, and thus doesn't allow custom keywords (such as javaType). As recommended in this blog post, custom annotations (such as this one) should be prefixed by "-x". Because renaming the keyword itself is a breaking change, jsonschema2pojo could just look for x-javaType if javaType is not found (the later takes precedence over the new one).

This would be more aligned with the JSON specs, and maybe improve compatibility with some external tools that would maybe otherwise break.

Thanks!

[joelittlejohn]

Thanks for brining this to my attention @dunivlorraine. Glad to hear that the working group is committing to this being the last breaking change 😄

It sounds like this goes well beyond javaType and extends to all extension keywords that jsonschema2pojo uses.

[ctrimble]

I am enjoying the fact that RFC 6648 recommended ending that practice for http headers and here we are right back at it. 😆

@joelittlejohn is this something the project wants to act on? I could work up a PR.

[ctrimble]

This might be a use case for a preprocessor.

[joelittlejohn]

No need to preprocess, I think we literally just look for both names. It's simple but effective.

[joelittlejohn]

I am enjoying the fact that RFC 6648 recommended ending that practice for http headers and here we are right back at it. 😆

Yeah, I'm trying to stay positive here in the face of the schema spec continually changing direction over the last 10 years :)

I do understand their issue. If you are relaxed about unrecognised fields (see Postel's law), then supporting a new optional property can be a breaking change if someone was using that name already. The addition of new optional properties should always be non-breaking. It's one reason why all jsonschema2pojo extension properties are named in a way that would never conflict with the spec (e.g. javaXxx).

In reality though we get the same problem all the way down. Adding a new optional extension property to jsonschema2pojo, even with the x- prefix, could still conflict with an extension property that someone else is already using. The 'x-' is a fix for JSON Schema itself but not for anyone else. Anyone with any sense should already be using their own convention to avoid a future conflict with the underlying spec, so the x- is a bit pointless.

'Evolution by accretion' is a great rule of thumb, but it isn't a silver bullet. The only real solution is that every addition is a breaking change (new major version) but let's face it, no-one wants that. So we apply rules that give us some chance to evolve whilst minimising breaking changes, even if we aren't actually eliminating them.

[dunivlorraine]

Oh I didn't know that JSON specs were changing guidelines so often!

In reality though we get the same problem all the way down. Adding a new optional extension property to jsonschema2pojo, even with the x- prefix, could still conflict with an extension property that someone else is already using. The 'x-' is a fix for JSON Schema itself but not for anyone else. Anyone with any sense should already be using their own convention to avoid a future conflict with the underlying spec, so the x- is a bit pointless.

You're right, prefixes don't really solve anything. This is not an issue on my end as I ended up removing that field and using a programmatic approach instead, but just so you know, some libraries or tools enforces the JSON specs strictly (Kafka Schema Registry is particularly annoying on that point).