Confusion around null values in spec and schema

[csuich2]

See this topic for context: swagger-api/swagger-js#268

When I discovered those exceptions in swagger-js, I initially thought it was just an issue of error handling in the JS. During that discussion, I was informed that the Swagger spec and schema technically do not support null values for some fields (get, post, put, operations, for example).

I just wanted to provide a little feedback as a new user that this was both a bit surprising and confusing. I tried reading through both the spec and schema to determine whether my APIs behavior of serializing null values contradicted the Swagger spec or schema but couldn't find anything that indicated either way.

All that said, I'm hoping someone can explain the decision to explicitly disallow null values for these types of fields. Serializing null values from APIs seems like something that isn't uncommon and not supporting that was just a bit surprising.

Thanks!
Chris

[webron]

Thanks for taking the time to open the issue.

JSON Schema requires you to mention that a property can be nullified. For example, take this schema:

{
  "type": "object",
  "properties": {
    "test": {
      "type": "string"
    }
  }
}

A fairly simple one, of an object with one property type that has a string value.
Using https://json-schema-validator.herokuapp.com, try validating the following two samples:

{
  "test": "hello"
}

{
  "test": null
}

You'll see that the one with the null value just doesn't validate. Since we never explicitly mention that in the JSON Schema, it means null is not a valid value anywhere. That said, the JSON Schema reflects on the spec itself, but the spec is the single source of truth. It's true that the spec does not mention it, as I had never thought it's required. Keep in mind that null is a meaningful value - when you omit a property, it means its value is not relevant for that object. However, when you nullify a property, you basically "erase" an existing value. This doesn't make much sense for the spec, plus it adds a lot of clutter and makes a spec much more difficult to read.

[maxfelker]

+1

[samwalshnz]

+1

[webron]

Tackling PR: #741

[webron]

#894 added null support in 3.0.

[marcelstoer]

This confused the heck out of me. I found some hints on this issue list scattered across various issues but I still opted to ask a simple question at https://stackoverflow.com/q/45575493/131929.

[darrelmiller]

@marcelstoer Answered on Stackoverflow.

@webron Unless I'm reading the JSON Schema spec wrong, it looks like that validator is invalid. null is always a valid string http://json-schema.org/latest/json-schema-validation.html#rfc.section.3.1

[webron]

which validator?

[darrelmiller]

The one you referenced here #297 (comment) to justify why null is not valid.

[webron]

Okay, and just so we're on the same page - did you reference draft 06's validation where that was for OAS2 that used draft 04?

[darrelmiller]

Draft 04 said the same thing https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-3.1

[darrelmiller]

This seems to come down to whether you consider the JSON concept of null as mapping to a string with the \x00 character.

[webron]

Are the nul character and null as a value the same thing?

I'll give you a hint why I think that wasn't the intent. Do you see the fge part in the draft 04 URL? That's the same guy who wrote the online validator for the test in #297 (comment).

[darrelmiller]

:-) LOL ok. That might be definitive then. I'll fix my answer on SO.