feat(new-rule): ibm-schema-naming-convention

.secrets.baseline

@@ -3,7 +3,7 @@
     "files": "package-lock.json|^.secrets.baseline$",
     "lines": null
   },
-  "generated_at": "2023-07-25T19:51:41Z",
+  "generated_at": "2023-09-07T18:22:20Z",
   "plugins_used": [
     {
       "name": "AWSKeyDetector"
@@ -94,6 +94,16 @@
         "type": "Secret Keyword",
         "verified_result": null
       }
+    ],
+    "packages/validator/test/cli-validator/mock-files/oas31/warn-threshold.yml": [
+      {
+        "hashed_secret": "1e5c2f367f02e47a8c160cda1cd9d91decbac441",
+        "is_secret": false,
+        "is_verified": false,
+        "line_number": 166,
+        "type": "Secret Keyword",
+        "verified_result": null
+      }
     ]
   },
   "version": "0.13.1+ibm.56.dss",

docs/ibm-cloud-rules.md

@@ -85,6 +85,7 @@ which is delivered in the `@ibm-cloud/openapi-ruleset` NPM package.
   * [ibm-resource-response-consistency](#ibm-resource-response-consistency)
   * [ibm-response-status-codes](#ibm-response-status-codes)
   * [ibm-schema-description](#ibm-schema-description)
+  * [ibm-schema-naming-convention](#ibm-schema-naming-convention)
   * [ibm-schema-type](#ibm-schema-type)
   * [ibm-schema-type-format](#ibm-schema-type-format)
   * [ibm-sdk-operations](#ibm-sdk-operations)
@@ -472,6 +473,12 @@ has non-form content.</td>
 <td>oas3</td>
 </tr>
 <tr>
+<td><a href="#ibm-schema-naming-convention">ibm-schema-naming-convention</a></td>
+<td>warn</td>
+<td>Schemas should follow the API Handbook naming conventions.</td>
+<td>oas3</td>
+</tr>
+<tr>
 <td><a href="#ibm-schema-type">ibm-schema-type</a></td>
 <td>off</td>
 <td>Schemas and schema properties should have a non-empty <code>type</code> field. <b>This rule is disabled by default.</b></td>
@@ -4872,6 +4879,77 @@ components:
 </table>
 
 
+### ibm-schema-naming-convention
+<table>
+<tr>
+<td><b>Rule id:</b></td>
+<td><b>ibm-schema-naming-convention</b></td>
+</tr>
+<tr>
+<td valign=top><b>Description:</b></td>
+<td>
+The name of each schema should follow the <a href="https://cloud.ibm.com/docs/api-handbook?topic=api-handbook-schemas#naming">IBM Cloud API Handbook schema naming conventions</a>.
+
+The rule checks the names of collection schemas, resource collection element schemas, creation/replacement schemas, and patch schemas against the name of the associated canonical schema to ensure the names follow the guidelines.
+</td>
+</tr>
+<tr>
+<td><b>Severity:</b></td>
+<td>warn</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:
+      requestBody:
+        content:
+          'application/json':
+            schema:
+              $ref: '#/components/schemas/ThingCreator' # Should be ThingPrototype
+  /v1/things/{id}:
+    get:
+      responses:
+        200:
+          content:
+            'application/json':
+              schema:
+                $ref: '#/components/schemas/Thing' # Canonical schema
+</pre>
+</td>
+</tr>
+<tr>
+<td valign=top><b>Compliant example:</b></td>
+<td>
+<pre>
+paths:
+  /v1/things:
+    post:
+      requestBody:
+        content:
+          'application/json':
+            schema:
+              $ref: '#/components/schemas/ThingPrototype'
+  /v1/things/{id}:
+    get:
+      responses:
+        200:
+          content:
+            'application/json':
+              schema:
+                $ref: '#/components/schemas/Thing'
+</pre>
+</td>
+</tr>
+</table>
+
+
 ### ibm-schema-type
 <table>
 <tr>

packages/ruleset/src/functions/index.js

@@ -50,6 +50,7 @@ module.exports = {
   responseExampleExists: require('./response-example-exists'),
   responseStatusCodes: require('./response-status-codes'),
   schemaDescriptionExists: require('./schema-description-exists'),
+  schemaNamingConvention: require('./schema-naming-convention'),
   schemaOrContentProvided: require('./schema-or-content-provided'),
   schemaTypeExists: require('./schema-type-exists'),
   schemaTypeFormat: require('./schema-type-format'),

packages/ruleset/src/functions/resource-response-consistency.js

@@ -8,6 +8,7 @@ const { isObject } = require('@ibm-cloud/openapi-ruleset-utilities');
 const {
   getResourceSpecificSiblingPath,
   getResponseCodes,
+  getSuccessResponseSchemaForOperation,
   isCreateOperation,
   isJsonMimeType,
   isOperationOfType,
@@ -167,9 +168,9 @@ function resourceResponseConsistency(operation, path, apidef) {
 
 function getCanonicalSchema(path, apidef) {
   const resourceSpecificPath = isOperationOfType('post', path)
-    ? getResourceSpecificSiblingPath(path, apidef)
+    ? getResourceSpecificSiblingPath(path.at(-2), apidef)
     : // This is a PUT or PATCH and should already be on the path we need
-      path[path.length - 2].toString().trim();
+      path.at(-2).trim();
 
   logger.debug(
     `${ruleId}: calculated resource-specific path to be "${resourceSpecificPath}"`
@@ -189,62 +190,11 @@ function getCanonicalSchema(path, apidef) {
     );
     return;
   }
-  if (!resourceGetOperation.responses) {
-    logger.debug(
-      `${ruleId}: no responses defined on GET operation at path "${resourceSpecificPath}"`
-    );
-    return;
-  }
 
-  const [, getOpSuccessCodes] = getResponseCodes(
-    resourceGetOperation.responses
-  );
-
-  logger.debug(
-    `${ruleId}: corresponding GET operation has the following status codes: ${getOpSuccessCodes.join(
-      ', '
-    )}`
-  );
-
-  if (
-    !getOpSuccessCodes ||
-    !getOpSuccessCodes.length ||
-    !getOpSuccessCodes.includes('200')
-  ) {
-    logger.debug(
-      `${ruleId}: no 200 success code found in responses defined on GET operation at path "${resourceSpecificPath}"`
-    );
-    return;
-  }
-
-  const successResponse = resourceGetOperation.responses['200'];
-  if (!successResponse.content || !isObject(successResponse.content)) {
-    return;
-  }
-
-  // Find the first content object determined to be JSON -
-  // we are only interested in JSON content.
-  const jsonMimeType = Object.keys(successResponse.content).find(mimeType =>
-    isJsonMimeType(mimeType)
-  );
-  if (!jsonMimeType) {
-    logger.debug(
-      `${ruleId}: no JSON content found on 200 response defined on GET operation at path "${resourceSpecificPath}"`
-    );
-    return;
-  }
-
-  const jsonContent = successResponse.content[jsonMimeType];
-  if (!isObject(jsonContent) || !jsonContent.schema) {
-    logger.debug(
-      `${ruleId}: no JSON content schema found in 200 response defined on GET operation at path "${resourceSpecificPath}"`
-    );
-    return;
-  }
-
-  logger.debug(
-    `${ruleId}: found schema in ${jsonMimeType} content object in 200 response defined on GET operation at path "${resourceSpecificPath}"`
+  const { schemaObject } = getSuccessResponseSchemaForOperation(
+    resourceGetOperation,
+    path
   );
 
-  return jsonContent.schema;
+  return schemaObject;
 }

packages/ruleset/src/functions/response-status-codes.js

@@ -168,7 +168,10 @@ function responseStatusCodes(operation, path, apidef) {
 }
 
 function hasBodyRepresentation(path, apidef) {
-  const resourceSpecificPath = getResourceSpecificSiblingPath(path, apidef);
+  const resourceSpecificPath = getResourceSpecificSiblingPath(
+    path.at(-2),
+    apidef
+  );
 
   logger.debug(
     `${ruleId}: calculated resource-specific path to be "${resourceSpecificPath}"`