Nullable properties with a default of null are not possible according to the 3.0 spec

From the spec…

default - The default value represents what would be assumed by the consumer of the input as the value of the schema if one is not provided. Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object defined at the same level. For example, if type is string, then default can be “foo” but cannot be 1.

This, combined with the fact that properties can be nullable, means that it’s not possible to have a property with a default value of null.

You can see below that the folks over at Swagger have interpreted the spec literally, as they should. It’s the spec that seems to be wrong.

Here’s a sample response body on my /todos/{id} route in the Swagger UI…

{
  "id": 0,
  "title": "string",
  "complete": false,
  "note": "null",
  "dueDate": "null",
  "categoryId": 0
}

And here’s the OpenAPI schema for my todo objects…

Todo:
  description: A todo item helps you track what you need to get done
  type: object
  required:
    - title
    - complete
  properties:
    id:
      type: integer
    title:
      type: string
    complete:
      type: boolean
      default: false
    note:
      type: string
      nullable: true
      default: null
    dueDate:
      type: string
      nullable: true
      default: null
    categoryId:
      type: integer
      nullable: true
      default: null

Looking at the note property, we can see that the default value of null gets interpreted as the string “null”.

Looking at categoryId, it seems that 0 is the closest integer to null they could think of.

[handrews]

If we need to further clarify the language in OAS 3.1, we should track this in #2099. Otherwise it sounds like maybe this can be closed?

[philsturgeon]

Dope! That PR is on the agenda so I’m gonna close this one on down.