[Schema Inaccuracy] nullable used in an odd (probably inaccurate) way

[mattpolzin]

Schema Inaccuracy

The POST request body schema at /gists defines oneOf the options for the public property to be nullable: true (without any type or enum restrictions).

This means "any type of thing, and it could be null" whereas I can only imagine the intention was simply to state "you are allowed to pass null in addition to a boolean or the strings 'true'/'false'."

From a human readability perspective, this is not really so bad -- I've picked the only interpretation that makes sense to me. From a tooling perspective, this makes a big difference. A tool cannot verify input or offer the user good code generation based on the knowledge that "any type of thing is allowed here."

Expected

To specify that null is one of the options without also allowing literally any type of input, I would at least expect to see

- nullable: true
  enum:
    - null

which would say "any type of thing, as long as that thing is null."

Really, I am not clear on why the enclosing definition is not simply

oneOf:
- description: Flag indicating whether the gist is public
  example: true
  type: boolean
- type: string
  nullable: true
  enum:
  - 'true'
  - 'false'
  - null

Which would allow for null values as part of the string option without adding the extra case.

[xuorig]

Thanks for the report @mattpolzin. We've removed nullable: true on the string version of the parameter because that's not actually something we support 👍 This is fixed on main.