feat(ibm-use-date-based-format): introduce new validation rule

.secrets.baseline

@@ -3,7 +3,7 @@
     "files": "package-lock.json|^.secrets.baseline$",
     "lines": null
   },
-  "generated_at": "2024-12-16T19:27:38Z",
+  "generated_at": "2024-12-19T16:14:03Z",
   "plugins_used": [
     {
       "name": "AWSKeyDetector"

docs/ibm-cloud-rules.md

@@ -114,6 +114,7 @@ which is delivered in the `@ibm-cloud/openapi-ruleset` NPM package.
   * [ibm-summary-sentence-style](#ibm-summary-sentence-style)
   * [ibm-unevaluated-properties](#ibm-unevaluated-properties)
   * [ibm-unique-parameter-request-property-names](#ibm-unique-parameter-request-property-names)
+  * [ibm-use-date-based-format](#ibm-use-date-based-format)
   * [ibm-valid-path-segments](#ibm-valid-path-segments)
   * [ibm-well-defined-dictionaries](#ibm-well-defined-dictionaries)
 
@@ -675,6 +676,12 @@ specific "allow-listed" keywords.</td>
 <td>oas3</td>
 </tr>
 <tr>
+<td><a href="#ibm-use-date-based-format">ibm-use-date-based-format</a></td>
+<td>warning</td>
+<td>Checks each schema and heuristically determines if it should be a string schema that uses a format of "date" or "date-time".</td>
+<td>oas3</td>
+</tr>
+<tr>
 <td><a href="#ibm-valid-path-segments">ibm-valid-path-segments</a></td>
 <td>error</td>
 <td>Checks each path string in the API to make sure path parameter references are valid within path segments.</td>
@@ -7197,6 +7204,66 @@ paths:
 </table>
 
 
+### ibm-use-date-based-format
+<table>
+<tr>
+<td><b>Rule id:</b></td>
+<td><b>ibm-use-date-based-format</b></td>
+</tr>
+<tr>
+<td valign=top><b>Description:</b></td>
+<td> Schemas or properties that are date-based (i.e. the values they model
+are dates or times) must be strings with a format of "date" or "date-time".
+This rule validates that is the case for relevant schemas, which are determined
+heuristically using the property name, in the case of schema properties, or
+the example value provided for a schema or property. 
+</td>
+</tr>
+<tr>
+<td><b>Severity:</b></td>
+<td>warning</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>
+Resource
+  type: object
+  properties:
+    created_at: # Name indicates it should be a date or date-time
+      type: integer
+    stamp: # Example value indicates it should be a date-time
+      type: string
+      example: '1990-12-31T23:59:60Z'
+    ...
+</pre>
+</td>
+</tr>
+<tr>
+<td valign=top><b>Compliant example:</b></td>
+<td>
+<pre>
+Resource
+  type: object
+  properties:
+    created_at:
+      type: string
+      format: date-time
+    stamp:
+      type: string
+      format: date-time
+      example: '1990-12-31T23:59:60Z'
+    ...
+</pre>
+</td>
+</tr>
+</table>
+
+
 ### ibm-valid-path-segments
 <table>
 <tr>

packages/ruleset/src/functions/collection-array-property.js

@@ -1,5 +1,5 @@
 /**
- * Copyright 2017 - 2023 IBM Corporation.
+ * Copyright 2017 - 2024 IBM Corporation.
  * SPDX-License-Identifier: Apache2.0
  */
 
@@ -33,7 +33,7 @@ module.exports = function (schema, _opts, context) {
  * property named "things" since that is the final path segment.
  * @param {*} schema a "success" response schema for a GET operation
  * @param {*} path the array of path segments indicating the "location" of "schema" within the API definition
- * @param {*} apidef the resolved API definition
+ * @param {*} apidef the unresolved API definition (the rule only deals with paths and operations)
  * @returns an array containing the violations found or [] if no violations
  */
 function collectionArrayProperty(schema, path, apidef) {

packages/ruleset/src/functions/index.js

@@ -78,6 +78,7 @@ module.exports = {
   unevaluatedProperties: require('./unevaluated-properties'),
   uniqueParameterRequestPropertyNames: require('./unique-parameter-request-property-names'),
   unusedTags: require('./unused-tags'),
+  useDateBasedFormat: require('./use-date-based-format'),
   validatePathSegments: require('./valid-path-segments'),
   wellDefinedDictionaries: require('./well-defined-dictionaries'),
 };

packages/ruleset/src/functions/no-ambiguous-paths.js

@@ -27,7 +27,7 @@ module.exports = function (paths, _options, context) {
  * 1. "/v1/clouds/{id}", "/v1/clouds/{cloud_id}"
  * 2. "/v1/clouds/foo", "/v1/clouds/{cloud_id}"
  * 3. "/v1/{resource_type}/foo", "/v1/users/{user_id}"
- * @param {*} apidef the entire API definition
+ * @param {*} paths map containing all path objects
  * @returns an array containing zero or more error objects
  */
 function checkAmbiguousPaths(paths) {