belgif / rest-guide

REST Guidelines of Belgian government institutions
https://www.belgif.be/specification/rest/api-guide/
Apache License 2.0
24 stars 4 forks source link

Guideline on nullable #189

Open pvdbosch opened 1 month ago

pvdbosch commented 1 month ago

Document that properties can't have explicit value null unless schema declares nullable: true in OAS 3.0. Can be added to [jsn-null].

In OAS2.0/Swagger null wasn't allowed at all (or ambiguously at best). That's why we specified: As JSON Merge Patch requests can not be fully specified as an OpenAPI data type, a MergePatch marker type should be used, defined in [common-v1.yaml](https://github.com/belgif/openapi-common/blob/master/src/main/openapi/common/v1/common-v1.yaml).

Do we update this rule for OAS 3.0? It would still require a detected merge patch type with a variant of the schema with nullable: true added everywhere.

Note that OAS 3.1 replaces this (backwards-incompatible) by the "null" type, e.g.

"myProperty":
  type: [string, null]