api-quality-spectral-ruleset 1.3.0-beta.4 → 1.3.0-beta.5

package/apq-spectral.yaml

@@ -17,7 +17,9 @@ functions:
   - apq-check-examples-coverage
   - apq-path-depth
   - apq-forbidden-characters
+  - apq-valid-response-schema
   - apq-path-param-query-conflict
+  - apq-schema-format
   - apq-security-required-response
   - apq-check-ambiguous-path
   - apq-password-format
@@ -218,7 +220,7 @@ rules:
     then:
       function: apq-alternate-paths
       functionOptions:
-        except: ["me"]
+        except: ["me", "get", "search"]
   apiq:OAR018:
     description: Operation not recommended for resource path depending on HTTP verb
     message: "OAR018: Operation not recommended for resource path: {{path}} ({{verb}})"
@@ -282,18 +284,44 @@ rules:
     description: "$expand must be defined as a query parameter in collection operations (excluding detail endpoints and health checks)."
     message: "OAR020: $expand must be defined as a query parameter in this operation."
     severity: warn
-    given: "$.paths[?(!@property.match(/\\/me(\\/|$)/) && !@property.match(/\\/\\{[^}]+\\}$/) && !@property.match(/status|health|ping/))].get.parameters"
+    given: "$.paths[?(!@property.match(/\\/me(\\/|$)/) && !@property.match(/\\/\\{[^}]+\\}$/) && !@property.match(/status|health|ping/))].get"
     then:
-      field: "$[?(@.name == '$expand' && @.in == 'query')]"
-      function: truthy
+      function: schema
+      functionOptions:
+        schema:
+          required: ["parameters"]
+          properties:
+            parameters:
+              type: array
+              contains:
+                type: object
+                properties:
+                  name:
+                    const: "$expand"
+                  in:
+                    const: query
+                required: [name, in]
   apiq:OAR021:
     description: "$exclude must be defined as a query parameter in collection operations (excluding detail endpoints and health checks)."
     message: "OAR021: $exclude must be defined as a query parameter in this operation."
     severity: warn
-    given: "$.paths[?(!@property.match(/\\/me(\\/|$)/) && !@property.match(/\\/\\{[^}]+\\}$/) && !@property.match(/status|health|ping/))].get.parameters"
+    given: "$.paths[?(!@property.match(/\\/me(\\/|$)/) && !@property.match(/\\/\\{[^}]+\\}$/) && !@property.match(/status|health|ping/))].get"
     then:
-      field: "$[?(@.name == '$exclude' && @.in == 'query')]"
-      function: truthy
+      function: schema
+      functionOptions:
+        schema:
+          required: ["parameters"]
+          properties:
+            parameters:
+              type: array
+              contains:
+                type: object
+                properties:
+                  name:
+                    const: "$exclude"
+                  in:
+                    const: query
+                required: [name, in]
   apiq:OAR022:
     description: "$orderby must be defined as a query parameter in all operations."
     message: "OAR022: $orderby must be defined as a query parameter in this operation."
@@ -496,24 +524,18 @@ rules:
         notMatch: "^(Cookie|Set-Cookie)$"
   apiq:OAR037:
     description: "Schema should use well-defined type and format."
-    message: "OAR037: String schemas must specify a valid format (date, date-time, password, byte, binary, email, uuid, uri, hostname, ipv4, ipv6, HEX, json, xml, or base64)."
+    message: "OAR037: String schemas must specify a valid format (date, date-time, password, byte, binary, email, uuid, uri, hostname, ipv4, ipv6, HEX, HEX(16), json, xml, or base64)."
     severity: error
-    given: "$..schema..[?(@.type=='string' && !@.enum)]"
+    given: "$..[?(@.type=='string')]"
     then:
-      field: format
-      function: pattern
-      functionOptions:
-        match: "^(date|date-time|password|byte|binary|email|uuid|uri|hostname|ipv4|ipv6|HEX|json|xml|base64)$"
+      function: apq-schema-format
   apiq:OAR038:
-    description: "Response schema must be compliant with the standard."
-    message: "OAR038: Response property is required for status code '{{property}}'."
+    description: "The 201 response schema of a POST operation must have properties named 'data' or 'error' with at least one sub-property."
+    message: "OAR038: Response property must be named 'data' or 'error'. Got '{{property}}'."
     severity: error
-    given: "$.paths.*.*.responses..content..schema.properties"
+    given: "$.paths.*.post.responses.*.content..schema.properties"
     then:
-      field: "@key"
-      function: pattern
-      functionOptions:
-        match: "^data|error$"
+      function: apq-valid-response-schema
   apiq:OAR039:
     description: "Response codes must be defined according to the standard depending on the HTTP verb and resource path."
     message: "{{error}}"
@@ -810,9 +832,9 @@ rules:
       - "$.paths.*.*.parameters[*].schema..properties.*~"
       - "$.paths.*.*.responses[*].schema..properties.*~"
     then:
-      function: casing
+      function: pattern
       functionOptions:
-        type: snake
+        match: "^([a-z$][a-z0-9_$]*|_[a-z0-9_]+|@[a-zA-Z][a-zA-Z0-9_]*|x-[a-zA-Z][a-zA-Z0-9_-]*)$"
   apiq:OAR067:
     description: "RequestBody and Responses schema property names must be compliant with the camelCase naming convention."
     message: "OAR067: RequestBody and Responses schema property names must be compliant with the camelCase naming convention."
@@ -871,10 +893,10 @@ rules:
       functionOptions:
         notMatch: "stacktrace"
   apiq:OAR073:
-    description: "API should include a 429 response to indicate rate limiting, except for health check paths like /status, /health, /ping."
+    description: "API should include a 429 response to indicate rate limiting, except for health check paths like /status, /health, /health-check, /ping, /liveness, /readiness."
     message: "OAR073: API should include a 429 response to indicate rate limiting."
     severity: error
-    given: "$.paths[?(!(@property.match(/\\/status|health|ping|liveness|readiness/)))][*].responses"
+    given: "$.paths[?(@property !== '/status' && @property !== '/health' && @property !== '/health-check' && @property !== '/ping' && @property !== '/liveness' && @property !== '/readiness')][*].responses"
     then:
       field: "429"
       function: truthy

package/functions/apq-alternate-paths.js

@@ -10,11 +10,14 @@ module.exports = (given, { except }, context) => {
 
   const parts = paths.substr(1).split('/').filter(p => p.length > 0);
   if (parts.length === 0) return result;
-  let previousIsVar = isVariable(parts.shift());
-  if (previousIsVar) {
-    return [{
-      message: context.rule.message,
-    }];
+  const firstPart = parts.shift();
+  let previousIsVar;
+  if (except && except.includes(firstPart)) {
+    previousIsVar = true;
+  } else if (isVariable(firstPart)) {
+    return [{ message: context.rule.message }];
+  } else {
+    previousIsVar = false;
   }
 
   for (const part of parts) {

package/functions/apq-forbidden-characters.js

@@ -6,18 +6,25 @@
 module.exports = (targetVal, _options, context) => {
   const pattern = /^[a-zA-Z0-9_\-., ]+$/;
   const errors = [];
+  const basePath = context.path || [];
 
   if (typeof targetVal === 'string') {
     if (!pattern.test(targetVal)) {
-      errors.push({ message: context.rule.message });
+      errors.push({
+        message: context.rule.message,
+        path: basePath
+      });
     }
   } else if (Array.isArray(targetVal)) {
     targetVal.forEach((role, index) => {
       if (typeof role === 'string' && !pattern.test(role)) {
-        errors.push({ message: context.rule.message, path: [index] });
+        errors.push({
+          message: context.rule.message,
+          path: [...basePath, index]
+        });
       }
     });
   }
 
   return errors;
-};
+};

package/functions/apq-schema-format.js

@@ -1,98 +1,13 @@
-// Check that format is valid for a schema type.
-
-/**
- * @param {object} given
- * @param {object} options
- * @param {object} options.formats
- * @param {Array<string>} options.formats.string
- * @param {Array<string>} options.formats.number
- * @param {Array<string>} options.formats.integer
- * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
- */
-module.exports = function checkTypeAndFormat(given, options, context) {
-  if (given === null || typeof given !== "object") {
-    return [];
-  }
-
-  const errors = [];
-  const path = context.path || [];
-
-  if (given.type === "string" && options.formats.string) {
-    if (given.format) {
-      if (!options.formats.string.includes(given.format)) {
-        errors.push({
-          message: `Schema with type string has unrecognized format: ${given.format}`,
-          path: [...path, "format"]
-        });
-      }
-    }
-  } else if (given.type === "integer" && options.formats.integer) {
-    if (given.format) {
-      if (!options.formats.integer.includes(given.format)) {
-        errors.push({
-          message: `Schema with type integer has unrecognized format: ${given.format}`,
-          path: [...path, "format"]
-        });
-      }
-    } else {
-      errors.push({
-        message: "Schema with type integer should specify format",
-        path
-      });
-    }
-  } else if (given.type === "number" && options.formats.number) {
-    if (given.format) {
-      if (!options.formats.number.includes(given.format)) {
-        errors.push({
-          message: `Schema with type number has unrecognized format: ${given.format}`,
-          path: [...path, "format"]
-        });
-      }
-    } else {
-      errors.push({
-        message: "Schema with type number should specify format",
-        path
-      });
-    }
-  } else if (given.type === "boolean") {
-    if (given.format) {
-      errors.push({
-        message: "Schema with type boolean should not specify format",
-        path: [...path, "format"]
-      });
-    }
-  } else if (given.properties && typeof given.properties === "object") {
-    // eslint-disable-next-line no-restricted-syntax
-    for (const [key, value] of Object.entries(given.properties)) {
-      errors.push(...checkTypeAndFormat(value, options, {
-        path: [...path, "properties", key],
-        document: context.document,
-        documentInventory: context.documentInventory,
-        rule: context.rule
-      }));
-    }
-  }
-
-  if (given.type === "array") {
-    errors.push(...checkTypeAndFormat(given.items, options, {
-      path: [...path, "items"],
-      document: context.document,
-      documentInventory: context.documentInventory,
-      rule: context.rule
-    }));
-  }
-
-  if (given.allOf && Array.isArray(given.allOf)) {
-    // eslint-disable-next-line no-restricted-syntax
-    for (const [index, value] of given.allOf.entries()) {
-      errors.push(...checkTypeAndFormat(value, options, {
-        path: [...path, "allOf", index],
-        document: context.document,
-        documentInventory: context.documentInventory,
-        rule: context.rule
-      }));
-    }
-  }
-
-  return errors;
+const VALID_FORMATS = new Set([
+  'date', 'date-time', 'password', 'byte', 'binary', 'email',
+  'uuid', 'uri', 'hostname', 'ipv4', 'ipv6', 'hex', 'hex(16)',
+  'json', 'xml', 'base64'
+]);
+
+module.exports = (targetVal, _options, context) => {
+  const format = targetVal.format;
+  if (format === undefined || format === null || !VALID_FORMATS.has(String(format).toLowerCase())) {
+    return [{ message: context.rule.message }];
+  }
+  return [];
 };

package/functions/apq-valid-response-schema.js

@@ -0,0 +1,39 @@
+/**
+ * @param {object} targetVal
+ * @param {object} _options
+ * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
+ */
+module.exports = (targetVal, _options, context) => {
+  const errors = [];
+  const VALID_NAMES = ['data', 'error'];
+
+  if (!targetVal || typeof targetVal !== 'object') {
+    return errors;
+  }
+
+  const path = context.path || [];
+  const responsesIdx = path.lastIndexOf('responses');
+  if (responsesIdx >= 0 && path[responsesIdx + 1] !== '201') {
+    return errors;
+  }
+
+  for (const [propName, propValue] of Object.entries(targetVal)) {
+    if (!VALID_NAMES.includes(propName)) {
+      errors.push({
+        message: context.rule.message,
+        path: [propName]
+      });
+    } else {
+      const subProps = propValue && propValue.properties;
+      const hasSubProps = subProps && Object.keys(subProps).length > 0;
+      if (!hasSubProps) {
+        errors.push({
+          message: `OAR038: Property '${propName}' must have at least one sub-property.`,
+          path: [propName]
+        });
+      }
+    }
+  }
+
+  return errors;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "api-quality-spectral-ruleset",
-  "version": "1.3.0-beta.4",
+  "version": "1.3.0-beta.5",
   "description": "Spectral ruleset by API Quality",
   "main": "apq-spectral.yaml",
   "files": [