nullable vs type arrays (JSON Schema compatibility)

I understand that fully supporting type arrays is a challenge for a variety of reasons. I would like to suggest that a compromise that would be functionally identical to nullable but compatible with JSON Schema:

• type MUST be a string or a two-element array with unique items
• if an array, one of the unique items MUST be "null"

The only way in which this is inherently more difficult to implement than nullable is that parsing type becomes slightly harder. The functionality, validation outcomes, code generation, etc. should be identical.

[philsturgeon]

I know this has been discussed greatly in the past, and as a brief recap:

I love OpenAPI, have been pushing it hard at work, and I also love contract testing. JSON Schema is fantastic at contract testing, doing this sort of thing:

@darrelmiller likes the idea, but this is really tricky as the very act of using JSON Schema is causing me to write invalid OAI files. I regularly use type: ['string', 'null'] and luckily various parsers support that, even though its invalid.

It’s so common for OAI users to use type: ['string', 'null'] that tools are already hacking in support on top of the spec, creating a superset of functionality that only works on some tools…

So that same thread @darrelmiller asked this question:

Do we special case that particular use of the array? Or do we give the middle finger to people who want to generate models?

Honestly it would be fantastic if there was some sort of solution that lead to JSON Schema and OAI handling types identically (supporting a recommendation for “Parameter Bags” to avoid giving out middle fingers as not all languages support union types, etc), but I will be happy to just avoid that whole can of worms.

I change my stance on this and suggest we go with @handrews’ proposal:

if an array, one of the unique items MUST be "null"

That would cover 99% of what people are trying to do. We’d still be left with an item on the “JSON Schema vs OAI discrepancies” list, but it wouldn’t cut quite so bad, and it would make thousands of invalid OAI files valid… 👍

[handrews]

We’d still be left with an item on the “JSON Schema vs OAI discrepancies” list

I think the key thing is that the remaining item would be a “feature of JSON Schema that is not supported”, while the current situation is “feature of JSON Schema that is functionally supported but requires a conflicting syntax”.

I’m not that bothered by a system saying “hey, we don’t quite want to use all of JSON Schema as defined for validation”. In fact, I want to spend effort in draft-08 making it easier to do that in general, so that projects like OpenAPI don’t have to awkwardly document the deltas and either write their own tooling or try to wrap up existing tooling some way to forbid bits and pieces.

With the two-element array option, and some effort in draft-08 around being able to declare support for things like vocabulary subsets, we could get OAI and JSON Schema fully compatible with each other, without requiring OAI to support everything JSON Schema dreams up for validation. After all, validation and code generation are really not the same things, and we should not pretend that they are.