Openapi-specification: add "null value support" in spec?

[fehguy]

Per https://github.com/swagger-api/swagger-core/issues/459 there are cases where passing null is important. For example:

[ null ]

will be quite different than []. See if this can be an option

[phil-scott-78]

Love to see this. Especially helpful for us with some of the datetime requirements we have. Right now I'm resorting to "x-isnullable" : true

[jphastings]

I'd like to see this too. I'm trying to define a PATCH endpoint which merges incoming fields of a JSON object over the existing one.

Accepting a document with age: null is the way I intend to specify that the value should be overwritten, rather than left as it currently is (which is what would happen when omitting the age key from the request).

(This usecase appears to be similar to chimmelb's referenced above. I could use JSONpatch, but it is overcomplex and requires oneOf to specify correctly )

[z0r1k]

Having null as type would be handy.
Otherwise in Response Class (Status 200) Model Schema you get

{
  "payload": {},
  "status": "ok"
}

instead of

{
  "payload": null,
  "status": "ok"
}

[webron]

@z0r1k - null normally makes sense in requests but less so in responses (though I can think of use cases it's useful for responses as well).

In your example, wouldn't it make more sense to just have the following if there's no payload?

{
  "status": "ok"
}

To me, null has the meaning of "this property existed before, and I want to nullify its value". If there's _no_ value, or the value needs not change (for requests, for example), it just shouldn't be sent.

[tuukkamustonen]

I'm in similar situation with jphastings (and chimmelb). Allowing null values is required for PATCH as I don't want to hack around that using empty strings or other magic variables. Support for null would be needed.

[bpicolo]

+1. Nullability is a sort of awkward thing to not have. It's definitely a distinct case from required. One is KEY must be present. One is VALUE of key must be present.

[freewilll]

+1. We're using the good suggestion by @enkafan too.

[jharmn]

+1 ran into this today, trying to validate responses in tests against Swagger schema.

A suggestion for a non-breaking change: nullable: true. This would avoid the problem of API developers being silly and implementing polymorphic fields (although I could see a Postel's Law argument on the request side).

[webron]

If you're suggesting x-nullable cough then sure, go ahead and use it for now :)

[wking]

On Sat, Dec 20, 2014 at 03:22:16PM -0800, Tony Tam wrote:

Per https://github.com/swagger-api/swagger-core/issues/459 there are
cases where passing null is important.

I bumped into this for enums (swagger-api/swagger-js#507) and was sent
here. Arguing for nulls in responses:

I restrict the information that gets returned to a user based on their
authorization. So using my pet.species example from
swagger-api/swagger-js#507, returning a response without pet.species
means “I won't tell you” and returning a response with a null
pet.species as null means “I don't know”.

Is the resistance to nulls in enums “this is too much work to
implement” (i.e. “patches welcome”) or “we disagree with JSON Spec's
choices” (i.e. “patches will be refused”).

[webron]

The 'resistance' is that 2.0 is finalized and won't change. There's no resistance to include it in a newer version of the spec (just need to make sure that we agree on the details).

[wking]

On Thu, Jun 25, 2015 at 12:51:54PM -0700, Ron wrote:

The 'resistance' is that 2.0 is finalized and won't change. There's
no resistance to include it in a newer version of the spec (just
need to make sure that we agree on the details).

The swagger 2.0 spec just defers to JSON Schema (latest!) for the enum
type [1,2] and it's listed as a “taken directly” property 3. So it
seems like swagger-js is just diverging from the spec, and could be
fixed in a 2.x.y patch relases. Users who currently don't use 'null'
in their specs won't be broken by us bringing swagger-js in line with
the spec in this regard. Or am I misunderstanding?

[webron]

null is not a valid type as it is not listed in the spec. You can't use an invalid type as a type for enum. There's no full compliance with JSON Schema, and while the spec defers to JSON Schema in some sections, it also imposes limitations on others. If you feel there needs to be extra clarification on null not being usable anywhere, I'll be happy to clarify it in the spec itself.

[wking]

On Thu, Jun 25, 2015 at 01:08:54PM -0700, Ron wrote:

null is not a valid type as it is not
listed
in the spec. You can't use an invalid type as a type for enum.

Ah, that makes sense.

If you feel there needs to be extra clarification on null not
being usable anywhere, I'll be happy to clarify it in the spec
itself.

The current spec does allow it in x-* fields, but yeah, I think more
clarity in the spec would help (so we don't have to refer folks here).

So that clears me up on the 2.0 issue. How do I go about working
towards adding a null datatype for 3.0? Just open a swagger-spec
issue? Is _this_ that issue? Should I PR swagger-js?

[webron]

This is the issue.

Nothing to PR on swagger-js, it won't change we start an official process for the next iteration of the spec (and I don't know when that will be).

[wking]

On Thu, Jun 25, 2015 at 01:19:11PM -0700, Ron wrote:

Nothing to PR on swagger-js, it won't change we start an official
process for the next iteration of the spec (and I don't know when
that will be).

No hurry, I'll just patch my copy locally until we get to it.

[webron]

Sounds good! Hopefully in the (not too far) future will have easier support for extensions (via vendor extensions) to the UI and that would make your patching easier, but can't make any promises as to when.

[jagg81]

I run into this same issue today. Specifically to my case, this makes Swagger harder to add support for in legacy systems, where breaking the API contract is not ideal or requires great effort.

+1 for supporting null values in future versions

[johndunlap]

I started getting this error after using the spec converter to upgrade my working 1.2 spec to 2.0. I hate null as much as the next guy but, this is the real world, and we can't just pretend that it doesn't exist. It does and, as such, it needs to be represented. What I've always liked about swagger was that it allowed me to describe my API without trying to force me to restructure it and this seems, at least to me, to be a major and very unsettling deviation from that role in my stack.

For the time being, I appear to have been given no choice but to continue using my 1.2 spec until this issue is addressed.

[webron]

Well, technically 1.2 doesn't allow it either. Just because the tools may be forgiving about it, doesn't mean it's supported.

[bpicolo]

Something to note:
https://github.com/swagger-api/swagger-core/issues/459 was closed in favor of this but this issue doesn't cover the whole issue that #459 does. When/if this is considered we definitely should look at it in terms of expanding to all array-of-types

[GiladShoham]

Hi,
i read all you wrote here, but i still don't fully understand.
i have situation like this:
i have some permission tree which every node is a role object.
every role has a field name parent which point to his role parent. but of course the root doesn't have a parent so he has null value for this field.
i have APIs to add and retrieve roles.
of course the user can't add new or other root, so he must have parent field for the new role.
but when he retrieve roles, he can get the root which has null.
currently i can't use the same scheme for post and get because for get the parent is not required / can be null but for post it's required.
(The same problem will be for post and patch because patch can update only specific fields like only the role name, so i need to make everything not required for patch)
is there any way i can use the same scheme for all? or at lease for post and get?

Thx.

[ikitommi]

So, the nullable types:

1. are valid to use in properties - swagger 2.0 spec references directly the JSON Schema which allows this - and we can assume this is not being dropped in the future? latest ui works also with these.
2. not supported in with operations

is this correct?

[webron]

Nope. They are invalid anywhere. The spec doesn't allow them, and that's the source of truth.

[GiladShoham]

@enkafan where can i found the x-isnullable implementation?
i want to use it as well.
Thx.

[phil-scott-78]

@GiladShoham - I'm using Swashbuckle as part of our .NET WebAPI project. It allows me to customize how it builds the scheme like so

var vendorExt = new Dictionary<string, object> { { "x-nullable", true } };
c.MapType<int?>(() => new Schema { type = "integer", format = "int32", vendorExtensions = vendorExt });

in it's configuration. this results in code that looks like

"LastUserId":{"format":"int32","type":"integer","x-nullable":true}

[nicksieger]

Adding my :+1: to nullable support in future versions of the spec. Unfortunately I'm leading a project that is going to ramp up heavy use of 2.0 across our organization soon, so it sucks that we'll have to write tooling around x-nullable or similar until the next version of the spec comes out.

[ikitommi]

how should then the allowEmptyValue be handled? The spec says:

Sets the ability to pass empty-valued parameters. This is valid only for either query or formData parameters and allows you to send a parameter with a name only or an empty value. Default value is false.

Still it does nothing, at least in the ui and it's a spec issue? see https://github.com/swagger-api/swagger-ui/issues/1396.

And, is it advised to use also the x-nullable for now?

[GiladShoham]

@enkafan
Thx for your response.
actually im writing the spec my self, so i can just add the x-nullable property, but i need the swagger validator to know what is this field.
so my question is what did you change in the validator to make this work?

[jpizarrom]

+1. We'll use the good suggestion by @enkafan too.

[pipermerriam]

Nope. They are invalid anywhere. The spec doesn't allow them, and that's the source of truth.

I feel like I'm missing something.

https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#schemaObject says _"The following properties are taken directly from the JSON Schema definition and follow the same specifications"_. the type field is included in that list, and json schema defines a null type.

I'm failing to see why using "type": ["null", "string"], "format": "datetime" would be invalid. This seems like a very clean way to implement nullability.

cc @webron

[webron]

@pipermerriam - it's just not supported. If you feel there's a need to clarify that around the type specifically, I'd be happy to add that. An array value in general is not allowed for type (regardless of null) so there's probably room for that explanation anyways.

Not disagreeing that it should have been supported, that there are ways to support it general or anything of that sort. It was an unfortunate aspect that wasn't included in this version of the spec or any of the previous ones. I'm afraid the only workaround for now is to use a vendor extension.

[pipermerriam]

An array value in general is not allowed for type

How do you reconcile that statement with:

• Json Schema says "The value of this keyword MUST be either a string or an array." which unambiguously states that the type keyword can be either a string or an array of strings. http://json-schema.org/latest/json-schema-validation.html#anchor79
• Swagger's 2.0 spec says "The following properties are taken directly from the JSON Schema definition and follow the same specifications:" which unambiguously says that the type keyword for a swagger Schema Object's definition is defined exactly as it is in json schema?

That statement that an array value is not allowed for the type keyword seems to directly contradict the spec.

cc @webron

[webron]

It's a discrepancy in the written spec. I'm human and I make mistakes too - and that was written before I realized JSON Schema allows for array values. Like I said in my previous comment, I'd be more than happy to clarify that in the spec itself. I'm afraid that mistake, however, doesn't change the fact that null nor array values are supported.

[pipermerriam]

Which document is considered the definitive source of truth for swagger?

On Mon, Dec 14, 2015, 4:26 PM Ron [email protected] wrote:

It's a discrepancy in the written spec. I'm human and I make mistakes too

• and that was written before I realized JSON Schema allows for array
  values. Like I said in my previous comment, I'd be more than happy to
  clarify that in the spec itself. I'm afraid that mistake, however, doesn't
  change the fact that null nor array values are supported.

—
Reply to this email directly or view it on GitHub
https://github.com/swagger-api/swagger-spec/issues/229#issuecomment-164592837
.

[fehguy]

@pipermerriam this was an error in the documentation. The spec doc is the source of truth and it was well written. That said, this is indeed an error and should be clarified.

[pipermerriam]

Forgive my directness. No intended hostility here. Just searching for
understanding.

I believe the cited reason for not spring this feature is that the swagger
2.0 spec is frozen.

If the spec document is the source of truth and the spec document
unambiguously states that this functionality is supported then it seems
logical that changing the spec document to not support this functionality
is equivalent to changing the spec. This revision would not be a
clarification. It would be an arbitrary change in the specification (which
is supposed to be frozen) as decided by the swagger developers.

My library flex currently supports this nullibility functionality as it was
written to implement the 2.0 specification.

Help me understand how making this change to the spec is a fix when nothing
is broken about the current wording? It really feels a lot like an
arbitrary change to a spec that is supposed to be frozen.

On Mon, Dec 14, 2015, 4:53 PM Tony Tam [email protected] wrote:

@pipermerriam https://github.com/pipermerriam this was an error in the
documentation. The spec doc
https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md
is the source of truth and it was well written. That said, this is indeed
an error and should be clarified.

—
Reply to this email directly or view it on GitHub
https://github.com/swagger-api/swagger-spec/issues/229#issuecomment-164597832
.

[fehguy]

What you're describing was not supposed to be in the spec, and therefore the intent of what is written is wrong. That's quite different than saying that it was "supposed to be there but because it's not, we're going to update the docs".

I know it may feel frustrating, but there are man, many projects that behave in the manner that the spec intends to describe, and therefore updating the documentation to the intention is the right thing todo.

The spec _is_ actively being developed. I encourage you to join in that conversation--2.0 is by no means the last version of the spec. In fact, the cooperation about the changes is now open and governed neutrally. If you want to be a part of that, go to https://openapis.org

[pipermerriam]

Semantics aside, I'm failing to understand the strong resistance to letting this functionality stand? Why exactly must this be changed to not allow this feature if it's something that people clearly want and the spec as written already allows it, and that you're clearly open to including in future versions of the spec.

[fehguy]

@pipermerriam next version, please wait for that. There is NO resistance to considering it in the future, but we are not amending the intended functionality of the 2.0 spec.

[pipermerriam]

Will you please confirm that the source of truth is not the spec document, but rather the intent of @fehguy / @webron / ??is there anyone else that should be in this list??.

[fehguy]

@pipermerriam this is an OSS project. Please feel free to participate but leave your attitude at home

[pipermerriam]

@fehguy I just don't understand what is happening here. You and @webron are contradicting each other.

• Either the spec document is the source of truth and it isn't frozen so you can change the spec
• Or the source of truth is not the document but rather the intent of some set of individuals and the spec is frozen but there is a bug in it so it needs to be fixed.

These two things cannot both be true. Which one is it.

If you change the wording in the spec to disallow arrays for the type keyword then any library author who wrote a _spec compliant_ implementation of the swagger 2.0 schema will need to go and change their implementation to be compliant.

I don't understand why you are so intent on changing this to disallow this feature. What is so important that you need to break spec-compliant implementations?

[fehguy]

please see https://github.com/swagger-api/swagger-spec/issues/229#issuecomment-164606645

[pipermerriam]

please see #229 (comment)

Am I correct that this comment by webron is referencing modifying language used in the swagger 2.0 spec?

[pipermerriam]

please see #229 (comment)

Also, will you please actually answer my question.

[pipermerriam]

Is the problem that swagger doesn't support the null type? It looks like http://editor.swagger.io/#/ at least supports using an array as the value of the type keyword.

If that's the problem, then I completely understand updating the current 2.0 spec to be clear that the data-types allowed for this value are only those that swagger defines.

[ralfhandl]

I'd love to have nullable primitives as well as nullable objects, this would make it much easier to use Swagger for describing OData services (#230)

[flavianh]

Would love to see this!

[rafaelgonzalez]

As a work around, I've been specifying null types with quotes, like this:

topic:
  type:
    - string
    - 'null'

This way those types do show up in swagger-ui (this is extracted from a successful response example):

This might be another somewhat related issue: the field does not appear in the example value when you assign a list to type (not necessarily containing null, any list of values seems to do it)

[ralfhandl]

I didn't realize that this is allowed because of the garbled response examples in Swagger UI. The Swagger schema inherits this feature from JSON Schema, and the prose specification doesn't disallow it. Swagger Editor even supports it:

I can switch between "null" and the non-null primitive type per property (here Description and DiscontinuedDate are switched to string).

Next place where I tried it is within parameter objects: here the prose specification and the schema clearly only allow single values, and Swagger UI breaks down when encountering an array of primitive types, but Swagger Editor gracefully accepts this and even offers the dropdown menu to switch between types:

Third situation where I need nullable types is with objects. Imagine a Person has a HomeAddress and a WorkAddress, both are nullable, and both refer to the same definition. I currently do this with an x-nullable extension property within the reference object

      HomeAddress:
        $ref: '#/definitions/ODataDemo.Address'
        x-nullable: true
      WorkAddress:
        $ref: '#/definitions/ODataDemo.Address'
        x-nullable: true

The correct JSON Schema construct would be

"anyOf":[
  {"$ref":"#/definitions/ODataDemo.Address"},
  {"type":"null"}
]

which is currently not allowed by Swagger/OpenAPI and both more verbose and harder to recognize for clients that are not validators.

So all in all I'd prefer a new keyword nullable that I can use for all three cases. I could also live with type arrays within parameter objects and anyOf within schema objects, and then would stick to x-nullable to cater for the non-validator clients.

[vitorbaptista]

I'm also :+1: for this.

My current workaround is deleting the null fields before returning the JSON. This works for me because my nullable fields aren't required, so Swagger doesn't complain if they're undefined.

[Shaun1]

+1
Definitely need to support null. Placeholders in arrays, purposefully empty values...
Not supporting a JSON primitive type makes for a weird inconsistency IMO.

[malakai97]

We have a required field for specifying that a key must exist or can be absent. It follows logically that the same would exist for values.

I think I have a common use case: my responses are paginated, and I provide a "next" field that has a URI to the next page. For the last page, "next" is null.

[gitfool]

I recently submitted Swashbuckle PR #776 which proposes using x-type and x-nullable vendor extensions. I'd appreciate any feedback.

[cbornet]

My 2 cents on this issue:

• The array type support for "type" parameter as defined in JSON Schema was never meant to be used with swagger. As I see it, it would cause issues with "format" (on which item of the array does the format apply ?), "default", and with code generation in strongly typed languages (if type is ["integer", "string"], on what Java type do I map in the POJO model ?).
• The current spec says that the JSON Schema "type" can be used but doesn't restrict on string type for it for the Schema Object like it does for the Parameter Object or Header Object. So IMO the v2.0 spec should be fixed to clarify this.
• Without the possibility of having array types, I don't know if there is an interest for a null type. In any case, the types allowed for "type" in Schema Object should also be clarified especially if null cannot be used.
• As for nullability of fields in Schema Object, I am more in favor of introducing "nullable" than a complex way of explaining that "type can be an array but in that case it has at most 2 elements and if it has 2 elements one of them is null". The change would obviously be in the next version of the spec and in the meantime swagger implementations can use "x-nullable"

[gitfool]

@cbornet I think we're agreeing that type should be a single type, not an array; I'm not thinking about using a separate null type at all, but we need a way to express null-ability of a type, hence the x-nullable extension is desired and sufficient to express this in the meantime. Hopefully nullable will replace it when the dust settles.

[cbornet]

@gitfool yes, that's my last point :smile:

[cbornet]

@fehguy @webron Could we have a "semi-official" definition of the nullable vendor-extension so that systems that decide to implement it all do it the same way ?
In short, should it be x-nullable: true/false or x-isNullable: true/false ?

[ikitommi]

That's a brilliant idea. Maybe there could be a wiki-page for all the common extensions (and libs using those)? Having x-oneOf & friends implemented in most web libs (and forked swagger-uis) gives a strong signal that they should be in the core.

[wparad]

Can someone explain how this is not already implemented with the required property? Doesn't it follow that if a field is not required, then it can be missing from the result document, and hence null can just be represented as not-present. Therefore isn't this a problem for the generator of choice to convert incoming fields which are not required as allowed as nullable. In strong-typed languages you would have to do that anyway, and in weak-typed dictionary checks of non-existent keys is the same as null
dictionary['missing-key'] == null => true

[cbornet]

@wparad you can see in #459 comments the difference between required and nullable.

[ePaul]

@wparad "On the wire" (i.e. when serialized as JSON), a property being absent is strictly different than a property having a null value. When mapping to dictionaries or class objects in object oriented languages, an absent key might be mapped to null (or whatever that language is using for this concept) (or a null value might be omitted), but it is actually not the same thing.

Also, for array elements there is no required property, and simply omitting an element might not work when the order/index is significant (i.e. when two arrays have corresponding entries).

[gitfool]

@cbornet None of the boolean names in the specification use an "is" prefix, so for consistency / sanity we should surely use x-nullable (rather than x-isNullable). :wink:

[j0hnsmith]

Here's my example of why null values are important. I have an array that represents the colour (RGBA) of an element, the definition I have is

RgbaArray:
  type: array
  items:
    type: number
    minimum: 0
    maximum: 1
  minItems: 4
  maxItems: 4

But some elements don't yet have a colour, so I'd like to be able to allow null as the colour in place of the array (as it's a required field), but can't.

[ePaul]

@j0hnsmith I guess in your case I would not make this property required, if it can happen that some elements don't have it.

(The array elements themselves might need to be nullable, though – if some color component is not known. Although I guess I wouldn't use an array either, but an object with named properties for the color components.)

[bpicolo]

@ePaul in the context of an array, the index in the array must be present. If you just remove it that's an entirely different array.

[ePaul]

@bpicolo Yes, but the example of @j0hnsmith wasn't of that form.

[bpicolo]

@ePaul Ah, correct. :)

[j0hnsmith]

@ePaul This _is_ a required field (as determined by another system), if I change that for the api then I have to handle it as a special case, possible but a workaround, I've got enough of those already.

There are parts of the spec that cause friction, this is one of those parts for me.

[ePaul]

@j0hnsmith Okay, so you have some existing API (implementation) which needs null instead of a non-existing property for a thing which is not existing, and want to describe this with OpenAPI, and this causes problems because OpenAPI has no support for nulls at all.

This reasoning is fine, it just was not what I did read out of your original comment. Sorry for any confusion.

[waqarazeem10p]

I have been hit by an error due to C# System.Nullable and redirected here. Therefore rather then populating this post I have created the question separately here http://discuss.jsonapi.org/t/handling-nullables-in-swagger/591. Need an expert advice.

[webron]

Tackling PR: #741

[DavidBiesack]

We also got a javascript exception (and swagger-ui would not render the API) when an "examples" object contained

   "null" : null

The exception in the Javascript debugger showed

:
TypeError: Swagger 2.0 does not support null types ([object Object]). See https://github.com/swagger-api/swagger-spec/issues/229. at Resolver.resolveAllOf (http://swagger.na.sas.com/swagger-ui/swagger-ui.js:2952:13) at Resolver.resolveAllOf (http://swagger.na.sas.com/swagger-ui/swagger-ui.js:2955:12) at Resolver.resolveAllOf (http://swagger.na.sas.com/swagger-ui/swagger-ui.js:2955:12) at Resolver.resolveAllOf (http://swagger.na.sas.com/swagger-ui/swagger-ui.js:2955:12) at Resolver.resolveAllOf (http://swagger.na.sas.com/swagger-ui/swagger-ui.js:2955:12) at Resolver.finish (http://swagger.na.sas.com/swagger-ui/swagger-ui.js:2674:10) at http://swagger.na.sas.com/swagger-ui/swagger-ui.js:2527:16 at Resolver.resolve (http://swagger.na.sas.com/swagger-ui/swagger-ui.js:2580:6) at obj.on.response (http://swagger.na.sas.com/swagger-ui/swagger-ui.js:1459:26) at responseInterceptor (http://swagger.na.sas.com/swagger-ui/swagger-ui.js:1995:12)
message : "Swagger 2.0 does not support null types ([object Object]).  See https://github.com/swagger-api/swagger-spec/issues/229."
stack
:
(...)
...
key : "null"

[osher]

_Editted_: fix silly typos and beautify

Gosh. This thread opened at Dec 21, 2014.
Unfortunately I have the feeling it will be dragged on for a long time.

One can argue that null value is as good as undefined, and therefore the attribute should be omitted entirely.
IMHO - that's a limited narrow thinking.
Strong-typed implementations will require this null - and we've seen references to such occurrences here.
Regardless to strong-typed languages, the example in the very first report in this thread shows a semantic difference between [] and [ null ] that matters to the user...

.

So. After finding how to represent null as 'null',
It seems the fuss is about a contradiction between the spec and the ..._intent_
The thing is that the intent was to deny multiple value for type, but the current language of the spec allows it.
The problem is that many people used this spec as their source of truth.
Here we saw mentions of swagger-ui, flex and json-schema and I know of proprietary implementations I cannot name here, naming their standard a super-set.
That sounds like a lose-lose to me.

Changing the spec that was stated as frozen smells bad to me.

.

So ok, We got a "bug" in the spec. When my PM tells me he has a "bug" in the task description - we check to whom this task description was presented. If it's only me - then we "fix" it.
Alas, here - this description was communicated with the world, and the length of this thread suggests that the world minds...

Except for ..._original intent_, I could not find any reason for the objection to adopt this spec.
This is an OSS, this is a community discussion, and proposal has been expressed.

So why won't we?

[lyschoening]

This has been interesting to follow. Google's Protocol Buffers v3 also omit a null type, which does simplify their message format but requires a few tricks, such as passing a message with a list of field names ("FieldMask") in order to be able to remove values on a partial update (PATCH).

Their message format would never allow a [null] but it does allow a [''] and that would have the same meaning. From their perspective, it actually makes it easier to work with strongly typed languages. (Note that strongly typed languages do not necessarily allow null for primitive types — an int[] in Java will have to become a Integer[] to accommodate this change)

OpenAPI has the same constraint and some of the same solutions, but this thread makes it sound as if this constraint was introduced without thought. Was null left out by accident? If not, what were the considerations behind leaving it out?

[szakrewsky]

It doesn't look like the spec has been updated to clarify this yet. This means that people will continue to run into this issue, and have to dig through search results until they find and read this entire thread. Is there a reason why? Is it just waiting on someone to submit a PR? It seems to be that the pr should:

1. change https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md to clarify the type property in schema objects is not an array and one of the OpenAPI types.
2. change https://github.com/OAI/OpenAPI-Specification/blob/master/schemas/v2.0/schema.json to make sure that apis that define types this way will fail validation. (Currently validation is successful and I think that is a big sense of confusion).

[fehguy]

We are not updating the 2.0 version, please follow the OpenAPI.next branch for changes in the next version of the spec.

[cbornet]

OAI v3 will be released in one month. Can we have a status on this very commented issue ?
It really seems important for a lot of people to have nullable support and actually a lot of implementations already support an "x-nullable" field. So it would be great to have this become an official "nullable" field and not postpone it to 2 more years. Or just close this issue if all this is really silly...

[fehguy]

@cbornet it won't be released in one month, it'll be in "first implementor draft" which means major changes will not be added.

I believe null support was added, I'll check through the merged PRs in the 3.0 working copy (which lives here as I think you know)

[cdekok]

It should be supported once the json schema support is merged: https://github.com/OAI/OpenAPI-Specification/pull/741
Then the anyOf type could be used (waiting for this too :)).
I suppose when that gets merged the issue could be closed.

[webron]

We're not not adding support for null as a type, but adding a property nullable.

[cdekok]

@webron does that mean json schema support will not be merged? as it's a lot easier to validate the output if it uses valid json schema.
If both options would be supported it would perhaps be a bit weird as it would be an own addition to the json schema spec.

[webron]

The PR does not add full JSON Schema support. And we will not have full JSON Schema support in 3.0.

[cdekok]

Is there any reason to support anyOf in json schema but not support a null type and instead add a nullable property? As there already is an entire ecosystem to do output validation if it would stick to json schema instead of reinventing the wheel.

[ikitommi]

:+1: on @cdekok. As the 3.0 rc is not out, there is time to do changes still? Was there a good reason for not to support null?

[webron]

It's been a while, so doing my best to remember. I believe the reason is that we don't allow multi-typed definitions (so you can't have type: [ 'string', 'null' ] and it's somewhat unlikely to define something that's always null. To overcome that, the nullable came in.

And before you ask - it's unlikely that we'll add support for multi-types in 3.0. Perhaps in the next iteration.

[cbornet]

Multitype support would be a nightmare for code generators...

[cdekok]

@webron the mentioned pull requests suggests that there would be a oneOf which would allow a null value to be added.

[webron]

@cdekok theoretically, yes. Hopefully, people will be wise enough with the usage of oneOf and anyOf. Regardless, for now, we won't be adding null as a type.

[RodH257]

So with JSON (yaml here) schema, we generally do this for nullability:

my_nullable_string:
  anyOf:
  - type: string
  - type: 'null'

we can't do that because of no support for type null, instead we should do:

my_nullable_string:
  type: string
  nullable: true

It's unfortunate that it doesn't match the JSON schema way of doing things so we can use tooling around that. But at least we'll be able to represent it somehow so its a step forward.

[cipresso]

Regarding nullable. Does it support query and path parameters? For example, GET /customer?phone=null to get customers who have no phone number set. When something is defined to be nullable, does that mean null=="null"==null for primitives, or are only objects supported?

[webron]

I don't understand what you mean by null="null"=null, but yes, it's supported for all parameters, including primitives.

[cipresso]

Maybe I'll ask another way. If a query parameter qp is of type string, and is nullable, does ?qp=null mean the value is the string "null" or an indication of null? Or is it up to interpretation?

[webron]

Got it. Fair question. I don't know, but it seems like it would be outside the scope of the spec, potentially.

When you define a primitive type, you give the meaning of a type to the text. In id=42, 42 can be a string, a number or an integer. The same would go for nullable. If you set it to true, as a producer, you might assume that means you translate null value not as a string, and can never have a null string value. We're not here to invent a way to separate between a null value and a null string for such parameters.

[cipresso]

Thanks for the clarification Ron. And I understand that if you put a stake in the ground either way someone would be unhappy.

[handrews]

FWIW in JSON Hyper-Schema, we specify that null, true, and false SHOULD become "null", "true", and "false" when used to fill out URI templates (including query parameters handled through URI Templates). That's not currently directly relevant to OpenAPI, but it's a data point for how it's being handled in a similar situation.

[webron]

We've added nullable as a solution in 3.0.0-RC0.

[mattdeboard]

This represents a divergence from the json-schema specification, right?

[webron]

In a sense.

[mattdeboard]

On one hand I respect your philosophy about not trying to be the product for every API, and think I'd make the same decision in your shoes.

On the other, I really wish Swagger was a superset of json-schema so the existing validation libraries out there, which seem to do a very good job, were a good fit for validating API responses against the Swagger docs.

[cdekok]

Cannot agree more I can't see any reason why you would want to make a frankenstein json-schema while it already can deal with null values.

[webron]

We're not opening this up for discussion again at this point. The decision was made for 3.0 and it won't change. We might revisit it in the future.

[philsturgeon]

We're not opening this up for discussion again at this point. The decision was made for 3.0 and it won't change. We might revisit it in the future.

Hey, it's the future! What's up April people. How are things looking today?

@webron I appreciate your strong stance, and your wish to avoid another bikeshed. It seems like there has been a lot of conversation around this, and I'd be interested to see the archives. For the casual observer however, it looks like this whole "type should be a string" thing is a cruel and unnecessary deviation from JSON Schema.

I've put off using Swagger for a _very_ long time due to the whole "it's kinda JSON Schema, but an old version, and we added some bits, and ignored some bits" situation. I think Open API 3.0 would be an absolutely amazing time to resolve a bunch of these known deviations, even if it involves a bit of extra work right now.

Do you have a link to a convincing argument for why type: ['string', 'null'] is going to be ignored, or is it just "meh dont want to" (which I also understand. #opensource).

(And yeah I know we can nullable: true but that's not my concern.)

[cbornet]

@philsturgeon swagger is used to generate code including in strongly typed languages so it' not possible to support multi type fields.

[natebrunette]

@cbornet I've always felt like that should up to the implementors. There's no reason a generator for a dynamic language couldn't allow multi types, but a strongly typed language generator could restrict it.

[darrelmiller]

@natebrunette This is a slippery slope to allowing tool vendors to optionally implement anything at which point, the value of the standard is severely reduced.

[cipresso]

The particular case of ["string", "null"] should be OK for a strongly-typed language. The type could be tested for null or a generator could create a type called StringOrNull with an isNull() method.

[handrews]

@philsturgeon swagger is used to generate code including in strongly typed languages so it' not possible to support multi type fields.

Are strongly typed languages the only use case for swagger? Dynamically typed languages are common in web programming, to put it mildly. Crippling them for the sake of strong static typing is an odd choice. If an API does not want to support clients in strongly typed languages that's a valid decision.

[mattdeboard]

I mean Option/Maybe/Optional etc. are real things so I don't get the static/strong typing argument here.

edit: anyway it seems this matter is still at its same status from a few months ago. Just sayin.

[philsturgeon]

Yeah, @darrelmiller, I don't think this is a conversation about "Yolo everyone can just do whatever they want.", I think @natebrunette was more suggesting that if a strongly typed language does not support union types, there are ways to handle JSON Schema's multiple types in that language that dont blow the whole thing up.

Value objects are a thing.

[darrelmiller]

@philsturgeon This whole conversation is much bigger than just type being an array. JSON Schema is much more suited to validating instance documents than it is at describing the shape of things. There are so many things you can do with JSON Schema that make projecting types from it challenging.

I'd rather move to using a far more constrained version of JSON schema that allows users to unambiguously describe the shape of payloads than to enable the full expressiveness of JSON Schema for validation.

However, I'm not sure that the subset of JSON Schema for modelling should be defined within the scope of the OAI and instead think it should be done under the umbrella of the JSON Schema work. With all the V3 work going on I haven't had time to bring this to the JSON Schema folks yet.

[cipresso]

This discussion is causing flashbacks to the challenges with supporting xsd:any, xsd:anyType in the XML glory days. I'm not advocating for reintroducing the horrors of xsd:any or xsd:anyType, but maybe the equivalent of xsi:nil.

[darrelmiller]

@cipresso And the new nullable property in V3 does that https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.md#fixed-fields-20 Admittedly not in the same way JSON Schema normally does it, but that's because we didn't want to re-open this can of worms :-)

[handrews]

@darrelmiller

However, I'm not sure that the subset of JSON Schema for modelling should be defined within the scope of the OAI and instead think it should be done under the umbrella of the JSON Schema work. With all the V3 work going on I haven't had time to bring this to the JSON Schema folks yet.

It is actually one of the three proposed new vocabularies, and the only one currently lacking a champion :-) We haven't really started any of these projects b/c all of the main contributors had Life Stuff(tm) going on for the last few months, but I do expect things to start moving on at least UI and Documentation soon (I see the Documentation vocabulary as focusing on the challenges of dynamic hypermedia as opposed to OpenAPI's focus on statically describable APIs).

https://github.com/json-schema-org/json-schema-vocabularies

[cbornet]

Also I'll add (again) that the swagger field "format" would be incompatible with an array of types.

[niquola]

+1 for subset of json schema for structure/shape definition.

While working with FHIR standard, which also mix structure definition and validation, i came up to conclusion - that separation of this concerns is a good thing (as well as tricky;)

From other side you also could provide a different place in swagger doc for validation by unconstrained json schema.