clarification jsn-null

create rule for merge patch
belgif · Nov 26, 2024 · 56e068b · 56e068b
1 parent df44483
commit 56e068b
Show file tree

Hide file tree

Showing 3 changed files with 39 additions and 10 deletions.
diff --git a/guide/src/main/asciidoc/changelog.adoc b/guide/src/main/asciidoc/changelog.adoc
@@ -1,4 +1,7 @@
 == Changelog
+* 2024-xx-xx
+** clarify use of `null` in <<rule-jsn-null>>
+** add rule <<rule-doc-patch>> for JSON Merge Patch and illustrate use of nullable properties
 * 2024-04-05
 ** update <<rule-oas-tags>>: add new guidelines on tags (declared, style, no more than one tag on an operation)
 ** new: rule <<rule-oas-comp>> applies naming guidelines on all types of components (previously in <<rule-oas-types>> only for schemas)

diff --git a/guide/src/main/asciidoc/json.adoc b/guide/src/main/asciidoc/json.adoc
@@ -51,7 +51,7 @@ This is because `enterpriseNumber` is a fixed denomination (declared in  Crossro
 [subs="normal"]
 ```json
 {
-  "name": "Belgacom",
+  "name": "Proximus",
   "employerId": 93017373,
   "enterprise": {
     "enterpriseNumber": "0202239951"
@@ -63,7 +63,10 @@ This is because `enterpriseNumber` is a fixed denomination (declared in  Crossro
 [rule, jsn-null]
 .Null values
 ====
-Properties with a `null` value SHOULD be stripped from the JSON message.
+
+Properties without a value SHOULD be stripped from the JSON message, instead of having a `null` value.
+
+For properties or parameters with a specified type, OpenAPI disallows `null` values by default, unless `nullable: true` is specified.
 
 A notable exception to this rule are JSON Merge Patch requests, in which a `null` value indicates the removal of a JSON property.
 
@@ -75,7 +78,7 @@ Note that this rule doesn't apply to empty values (e.g. empty strings `""` or em
 a|[subs="normal"]
 ```json
 {
-  "name": "Belgacom",
+  "name": "Proximus",
   "employerId": 93017373,
   "enterprise": null
 }
@@ -84,7 +87,7 @@ a|[subs="normal"]
 a|[subs="normal"]
 ```json
 {
-  "name": "Belgacom",
+  "name": "Proximus",
   "employerId": 93017373
 }
 ```
@@ -97,7 +100,7 @@ a|[subs="normal"]
 a|[subs="normal"]
 ```json
 {
-  "name": "Belgacom",
+  "name": "Proximus",
   "employerId": 93017373
 }
 ```
@@ -107,7 +110,7 @@ a|[subs="normal"]
 ```json
 {
   "employerId": 93017373,
-  "name": "Belgacom"
+  "name": "Proximus"
 }
 ```
 |===

diff --git a/guide/src/main/asciidoc/resources-document.adoc b/guide/src/main/asciidoc/resources-document.adoc
@@ -625,16 +625,24 @@ a|
 [[document-partial-update]]
 ==== Partial update
 
+[rule, doc-patch]
+.JSON Merge patch
+====
 Use `PATCH` when you like to do a partial update of a document resource.
 
-The `PATCH` message MUST conform to the JSON Merge Patch (https://tools.ietf.org/html/rfc7386[RFC 7386]) specification:
+The `PATCH` message SHOULD conform to the JSON Merge Patch (https://tools.ietf.org/html/rfc7386[RFC 7386]) specification:
 
 * JSON properties in the request overwrite the ones in the previous resource state
 * properties with value `null` in the request are removed from the resource
 * properties not present in the request are preserved
 
 APIs should support both the media type of JSON merge patch `application/merge-patch+json` as the generic `application/json` JSON media type.
-As JSON Merge Patch requests can not be fully specified as an OpenAPI data type, a MergePatch marker type should be used, defined in https://github.com/belgif/openapi-common/blob/master/src/main/openapi/common/v1/common-v1.yaml[common-v1.yaml].
+
+Properties that can be removed, must have `nullable: true` in the OpenAPI 3.0 schema describing the JSON Merge Patch request, which is an exception to <<rule-jsn-null>>.
+Swagger 2.0 does not allow to document the use of `null` values. Instead, a `MergePatch` marker type should be used, defined in https://github.com/belgif/openapi-common/blob/master/src/main/swagger/common/v1/common-v1.yaml[common-v1.yaml].
+
+JSON Merge Patch requests SHOULD be represented by a different schema than other document operations (create, consult or full update), because otherwise `required` properties may be absent and `null` values may be allowed.
+====
 
 .JSON merge patch
 ====
@@ -646,13 +654,13 @@ PATCH {API}/employers/93017373[^] HTTP/1.1
 [cols="1,2,3"]
 |===
 |<<patch>>
-|/employers/{employerId}
+|`/employers/{employerId}`
 |Performs a partial update of an existing employer.
 
 3+|Request
 
 |body
-|JSON Merge Patch
+|`application/merge-patch+json` or  `application/json`
 a|
 [source,json]
 ----
@@ -662,6 +670,21 @@ a|
 }
 ----
 
+|schema
+|`EmployerPatch`
+a|
+[source,yaml]
+----
+type: object
+properties:
+  bankrupt:
+    type: boolean  # mandatory property, shouldn't be nullable
+  bankruptDate:
+    type: string
+    format: date
+    nullable: true # optional property, use null to remove it
+----
+
 3+|Parameters
 
 |`employerId`|path-param|employer ID of NSSO uniquely identifying the employer.