feat(ibm-no-required-properties-in-optional-body): introduced new rule (

#683)

This commit introduces the new "ibm-no-required-properties-
in-optional-body" validation rule, and deprecates the
"ibm-no-optional-properties-in-required-body" rule.
Essentially, we're just changing the rule id, but we are
providing backward compatibility by retaining (but deprecating)
the old rule id.

Signed-off-by: Phil Adams <[email protected]>

docs/ibm-cloud-rules.md

@@ -66,6 +66,7 @@ which is delivered in the `@ibm-cloud/openapi-ruleset` NPM package.
   * [ibm-no-operation-requestbody](#ibm-no-operation-requestbody)
   * [ibm-no-optional-properties-in-required-body](#ibm-no-optional-properties-in-required-body)
   * [ibm-no-ref-in-example](#ibm-no-ref-in-example)
+  * [ibm-no-required-properties-in-optional-body](#ibm-no-required-properties-in-optional-body)
   * [ibm-no-space-in-example-name](#ibm-no-space-in-example-name)
   * [ibm-no-superfluous-allof](#ibm-no-superfluous-allof)
   * [ibm-no-unsupported-keywords](#ibm-no-unsupported-keywords)
@@ -361,9 +362,12 @@ which is not allowed.</td>
 </tr>
 <tr>
 <td><a href="#ibm-no-optional-properties-in-required-body">ibm-no-optional-properties-in-required-body</a></td>
-<td>info</td>
+<td>off</td>
 <td>If a requestBody schema contains properties that are defined as required, then the requestBody itself
-should probably be required instead of optional.</td>
+should probably be required instead of optional.
+
+This rule is deprecated. Please use the <code>ibm-no-required-properties-in-optional-body</code> rule instead.
+</td>
 <td>oas3</td>
 </tr>
 <tr>
@@ -373,6 +377,13 @@ should probably be required instead of optional.</td>
 <td>oas3</td>
 </tr>
 <tr>
+<td><a href="#ibm-no-required-properties-in-optional-body">ibm-no-required-properties-in-optional-body</a></td>
+<td>info</td>
+<td>If a requestBody schema contains properties that are defined as required, then the requestBody itself
+should probably be required instead of optional.</td>
+<td>oas3</td>
+</tr>
+<tr>
 <td><a href="#ibm-no-space-in-example-name">ibm-no-space-in-example-name</a></td>
 <td>warn</td>
 <td>The name of an entry in an <code>examples</code> field should not contain a space.</td>
@@ -3627,11 +3638,13 @@ paths:
 Specifically, this rule examines the schemas associated with optional request bodies and
 if there are required properties, then it is likely that the API author intended for the
 request body to be required.
+
+This rule is deprecated.  Please use the <code>ibm-no-required-properties-in-optional-body</code> rule instead.
 </td>
 </tr>
 <tr>
 <td><b>Severity:</b></td>
-<td>info</td>
+<td>off</td>
 </tr>
 <tr>
 <td><b>OAS Versions:</b></td>
@@ -3734,6 +3747,65 @@ paths:
 </table>
 
 
+### ibm-no-required-properties-in-optional-body
+<table>
+<tr>
+<td><b>Rule id:</b></td>
+<td><b>ibm-no-required-properties-in-optional-body</b></td>
+</tr>
+<tr>
+<td valign=top><b>Description:</b></td>
+<td>This rule scrutinizes optional request bodies because in most cases, they should be required.
+Specifically, this rule examines the schemas associated with optional request bodies and
+if there are required properties, then it is likely that the API author intended for the
+request body to be required.
+</td>
+</tr>
+<tr>
+<td><b>Severity:</b></td>
+<td>info</td>
+</tr>
+<tr>
+<td><b>OAS Versions:</b></td>
+<td>oas3</td>
+</tr>
+<tr>
+<td valign=top><b>Non-compliant example:<b></td>
+<td>
+<pre>
+paths:
+  '/v1/things':
+    post:
+      operationId: create_thing
+      requestBody:
+        required: false
+        content:
+          'application/json':
+            schema:
+              $ref: '#/components/schemas/Thing'    # Assume "Thing" schema has required properties
+</pre>
+</td>
+</tr>
+<tr>
+<td valign=top><b>Compliant example:</b></td>
+<td>
+<pre>
+paths:
+  '/v1/things':
+    post:
+      operationId: create_thing
+      requestBody:
+        required: true
+        content:
+          'application/json':
+            schema:
+              $ref: '#/components/schemas/Thing'    # Assume "Thing" schema has required properties
+</pre>
+</td>
+</tr>
+</table>
+
+
 ### ibm-no-space-in-example-name
 <table>
 <tr>