api-quality-spectral-ruleset 1.4.0 → 1.4.1-beta.2

package/apq-spectral.yaml

@@ -29,6 +29,7 @@ functions:
   - apq-paged-response-check
   - apq-status-endpoint-check
   - apq-validate-structure
+  - apq-numeric-parameter-integrity
 extends:
   - spectral:asyncapi
   - spectral:oas
@@ -65,7 +66,7 @@ rules:
         message: "Scope must define a 'description' attribute."
   apiq:OAR004:
     description: "A role with forbidden characters may cause problems in some applications."
-    message: "OAR004: Role should not contain forbidden characters (e.g. special characters like €, *, etc.)."
+    message: "{{error}}"
     documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR004.md"
     severity: "error"
     given: "$.x-wso2-security.apim.x-wso2-scopes[*].roles"
@@ -166,7 +167,7 @@ rules:
       function: truthy
   apiq:OAR014:
     description: "Resources depth level should be below the non-suggested range."
-    message: "OAR014: The number of parts of the path must be less than 4."
+    message: "{{error}}"
     documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR014.md"
     severity: warn
     given: "$.paths.*~"
@@ -179,13 +180,13 @@ rules:
           - me
   apiq:OAR015:
     description: "Resources depth level should be smaller than 5."
-    message: "OAR015: Path exceeds the maximum allowed depth level of 5."
+    message: "{{error}}"
     severity: error
     given: "$.paths.*~"
     then:
       function: apq-path-depth
       functionOptions:
-        maxDepth: 5
+        max-level-allowed: 5
         ignoreSegments:
           - me
   apiq:OAR016:
@@ -193,7 +194,7 @@ rules:
     message: "OAR016: Numeric types must use a valid format for their type."
     documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR016.md"
     severity: error
-    given: "$..[?(@.type=='number' || @.type=='integer')]"
+    given: "$..[?(@ && (@.type=='number' || @.type=='integer'))]"
     then:
       function: schema
       functionOptions:
@@ -492,11 +493,13 @@ rules:
         paging-schema: '{"type":"object","properties":{"numPages":{"type":"integer"},"total":{"type":"integer"},"start":{"type":"integer"},"limit":{"type":"integer"},"links":{"type":"object","properties":{"next":{"type":"object","properties":{"href":{"type":"string"}}},"previous":{"type":"object","properties":{"href":{"type":"string"}}},"last":{"type":"object","properties":{"href":{"type":"string"}}},"self":{"type":"object","properties":{"href":{"type":"string"}}},"first":{"type":"object","properties":{"href":{"type":"string"}}}},"required":["self","previous","next"]}},"required":["start","limit","links"],"pagingPropertyName":"paging"}'
   apiq:OAR035:
     description: "Response code 401 must be defined for operations with security schemes defined."
-    message: "OAR035: Response code 401 must be defined for operations with security schemes defined."
+    message: "{{error}}"
     severity: "error"
     given: "$.paths[*][*]"
     then:
       function: apq-security-required-response
+      functionOptions:
+        expected-codes: "401"
   apiq:OAR036:
     description: "Cookie use is forbidden as a session mechanism."
     message: "OAR036: Cookie use is forbidden as a session mechanism."
@@ -514,7 +517,7 @@ rules:
     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), or a valid pattern when no format is defined."
     severity: error
     resolved: false
-    given: "$..[?(@.type=='string')]"
+    given: "$..[?(@ && @.type=='string')]"
     then:
       function: apq-schema-format
   apiq:OAR038:
@@ -566,13 +569,13 @@ rules:
           ;patch:^/[^/{}]+/(\{[^/{}]+\}|\bme\b)/[^/{}]+/(\{[^/{}]+\}|\bme\b)/[^/{}]+/(\{[^/{}]+\}|\bme\b)$:200,404,400,415,500,503
   apiq:OAR040:
     description: "A scope name non-compliant with the standard may cause problems at application level."
-    message: "OAR040: Scope name value is non compliant with the standard."
+    message: "{{error}}"
     severity: "error"
     given: "$.x-wso2-security.apim.x-wso2-scopes[*].name"
     then:
-      function: pattern
+      function: apq-forbidden-characters
       functionOptions:
-        match: "^[a-zA-Z]{4,}_(SC|sc)_[a-zA-Z0-9]{1,}$"
+        pattern: "^[a-zA-Z]{4,}_(SC|sc)_[a-zA-Z0-9]{1,}$"
   apiq:OAR041:
     description: Available scopes must be defined at the end of the document, at the root level, inside `x-wso2-security`.
     message: "OAR041:Scopes must be defined in `x-wso2-security` at the end of the document, before the paths."
@@ -618,7 +621,7 @@ rules:
     then:
       function: pattern
       functionOptions:
-        match: "^(\\*|[a-zA-Z0-9.][a-zA-Z0-9.!#$&_^+\\-]+)/(\\*|[a-zA-Z0-9.][a-zA-Z0-9.!#$&_^+\\-]+(; charset=[a-zA-Z0-9_\\-]+)?)$"
+        match: '^(\*|[a-zA-Z0-9][a-zA-Z0-9.!#$&^_+\-]*)/(\*|[a-zA-Z0-9][a-zA-Z0-9.!#$&^_+\-]*)(?:[ \t]*;[ \t]*[a-zA-Z0-9!#$%&''*+\-.^_`|~]+=(?:[a-zA-Z0-9!#$%&''*+\-.^_`|~]+|"(?:[^"\\]|\\.)*"))*$'
   apiq:OAR045:
     description: "Response schema is required for responses with status codes 201 and others that return content."
     message: "OAR045: Response schema is required for status code '{{property}}'."
@@ -715,7 +718,7 @@ rules:
     message: "OAR052: Numeric types requires a format"
     documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR052.md"
     severity: warn
-    given: "$..[?(@.type == 'integer' || @.type == 'number')]"
+    given: "$..[?(@ && (@.type == 'integer' || @.type == 'number'))]"
     then:
       field: format
       function: truthy
@@ -853,8 +856,8 @@ rules:
       functionOptions:
         type: pascal
   apiq:OAR069:
-    description: "Path parameters should not appear as query parameters."
-    message: "OAR069: Path parameter should not appear as both path and query parameter."
+    description: "Any param in PATH or QUERY should have a Bad Request (400) response."
+    message: "OAR069: Any param in PATH or QUERY should have a Bad Request (400) response."
     severity: "error"
     given: "$.paths"
     then:
@@ -900,26 +903,20 @@ rules:
       field: "429"
       function: truthy
   apiq:OAR074:
-    description: "Numeric parameters should have minimum, maximum, or format restriction."
-    message: "OAR074: Numeric parameter '{{property}}' should have a minimum, maximum, or format restriction."
+    description: "Numeric parameters should define minimum and maximum, or a format restriction."
+    message: "OAR074: Numeric parameter should define both 'minimum' and 'maximum', or a 'format' restriction."
     severity: error
-    given: "$.paths[*][get,post,put,patch,delete].parameters[?(@.schema.type == 'integer' || @.schema.type == 'number')]"
+    resolved: false
+    given:
+      - "$..[?(@ && @.in && @.schema && (@.schema.type == 'integer' || @.schema.type == 'number'))].schema"
+      - "$..[?(@ && @.in && (@.type == 'integer' || @.type == 'number'))]"
     then:
-      function: schema
-      functionOptions:
-        schema:
-          type: object
-          properties:
-            schema:
-              anyOf:
-                - required: ["minimum"]
-                - required: ["maximum"]
-                - required: ["format"]
+      function: apq-numeric-parameter-integrity
   apiq:OAR075:
     description: "String parameters should have minLength, maxLength, pattern (regular expression), or enum restriction."
     message: "OAR075: String parameters should have minLength, maxLength, pattern, or enum restriction."
     severity: error
-    given: "$.paths[*][get,post,put,patch,delete].parameters[?(@.schema.type == 'string' && @.in == 'path')]"
+    given: "$.paths[*][get,post,put,patch,delete].parameters[?(@ && @.schema && @.schema.type == 'string' && @.in == 'path')]"
     then:
       function: schema
       functionOptions:
@@ -937,7 +934,7 @@ rules:
     message: "OAR076: Schema should use well-defined type and format."
     documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR076.md"
     severity: error
-    given: "$..[?(@.type=='number' || @.type=='integer')]"
+    given: "$..[?(@ && (@.type=='number' || @.type=='integer'))]"
     then:
       function: schema
       functionOptions:
@@ -1009,7 +1006,7 @@ rules:
     description: "The string properties 'product', 'line', and 'price' must define a byte or binary format."
     message: "{{error}}"
     severity: error
-    given: "$..[?(@.properties)]"
+    given: "$..[?(@ && @.properties)]"
     then:
       function: apq-binary-format-check
       functionOptions:
@@ -1035,7 +1032,7 @@ rules:
       functionOptions:
         notMatch: "^password$"
   apiq:OAR085:
-    description: "The OpenAPI version must be one of: 2.0, 3.0.0, 3.0.1, 3.0.2, 3.0.3, 3.1.0."
+    description: "The OpenAPI version must be one of: 2.0, 3.0.0, 3.0.1, 3.0.2, 3.0.3, 3.1.0, 3.2.0."
     message: "{{error}}"
     severity: warn
     given:
@@ -1044,7 +1041,7 @@ rules:
     then:
       function: apq-valid-openapi-version
       functionOptions:
-        valid-versions: "2.0,3.0.0,3.0.1,3.0.2,3.0.3,3.1.0"
+        valid-versions: "2.0,3.0.0,3.0.1,3.0.2,3.0.3,3.1.0,3.2.0"
   apiq:OAR086:
     description: "Descriptions must begin with a capital letter, end with a period, and not be empty."
     message: "OAR086: Descriptions must begin with a capital letter, end with a period, and not be empty."
@@ -1124,13 +1121,13 @@ rules:
       function: falsy
   apiq:OAR096:
     description: "Response code 403 must be defined for operations with security schemes defined."
-    message: "OAR096: Response code 403 must be defined for operations with security schemes defined."
+    message: "{{error}}"
     severity: "error"
-    given: "$.paths[*][*].responses"
+    given: "$.paths[*][*]"
     then:
-      function: truthy
-      field: "403"
-      message: "Operation must define a 403 Unauthorized response for security schemes."
+      function: apq-security-required-response
+      functionOptions:
+        expected-codes: "403"
   apiq:OAR097:
     description: "The base path must contain at least two parts."
     message: "OAR097: Path has too few parts."

package/functions/apq-binary-format-check.js

@@ -18,6 +18,10 @@ module.exports = (schema, options = {}, context) => {
       return;
     }
 
+    if (!propSchema || typeof propSchema !== 'object') {
+      return;
+    }
+
     // Check if it's a string type
     if (propSchema.type !== 'string') {
       return;

package/functions/apq-forbidden-characters.js

@@ -4,14 +4,16 @@
  * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
  */
 module.exports = (targetVal, options, context) => {
-  const pattern = new RegExp((options && options.pattern) || '^[a-zA-Z0-9_\\-., ]+$');
+  const patternStr = (options && options.pattern) || '^[a-zA-Z0-9_\\-., ]+$';
+  const pattern = new RegExp(patternStr);
   const errors = [];
   const basePath = context.path || [];
+  const buildMessage = (value) => `Value '${value}' does not match the required pattern: ${patternStr}.`;
 
   if (typeof targetVal === 'string') {
     if (!pattern.test(targetVal)) {
       errors.push({
-        message: context.rule.message,
+        message: buildMessage(targetVal),
         path: basePath
       });
     }
@@ -19,7 +21,7 @@ module.exports = (targetVal, options, context) => {
     targetVal.forEach((role, index) => {
       if (typeof role === 'string' && !pattern.test(role)) {
         errors.push({
-          message: context.rule.message,
+          message: buildMessage(role),
           path: [...basePath, index]
         });
       }

package/functions/apq-numeric-parameter-integrity.js

@@ -0,0 +1,31 @@
+/**
+ * @param {object} node
+ * @param {object} options
+ * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
+ */
+module.exports = (node, options, context) => {
+  const results = [];
+
+  if (!node || typeof node !== 'object') return results;
+
+  const { type } = node;
+  if (type !== 'integer' && type !== 'number') return results;
+
+  const has = (field) => Object.prototype.hasOwnProperty.call(node, field);
+  const hasMin = has('minimum');
+  const hasMax = has('maximum');
+  const hasFormat = has('format');
+
+  const hasBothBounds = hasMin && hasMax;
+  const formatAlone = hasFormat && !hasMin && !hasMax;
+
+  if (hasBothBounds || formatAlone) return results;
+
+  const ruleCode = context.rule.name.split(':').pop();
+  results.push({
+    message: `${ruleCode}: Numeric parameter should define both 'minimum' and 'maximum', or a 'format' restriction.`,
+    path: [...context.path, 'type'],
+  });
+
+  return results;
+};

package/functions/apq-path-depth.js

@@ -5,7 +5,7 @@
  */
 module.exports = (targetVal, options, context) => {
   const minDepth = options['min-level'] ?? options.minDepth ?? null
-  const maxDepth = options['max-level'] ?? options.maxDepth ?? 3
+  const maxDepth = options['max-level'] ?? options['max-level-allowed'] ?? options.maxDepth ?? 3
   const ignore = options.ignoreSegments ?? []
   const segments = targetVal
     .split('/')
@@ -20,8 +20,11 @@ module.exports = (targetVal, options, context) => {
     : depth > maxDepth
 
   if (isOutOfRange) {
+    const message = minDepth != null
+      ? `OAR014: Path depth (${depth}) must not fall within the non-suggested range ${minDepth}-${maxDepth}.`
+      : `OAR015: Path depth (${depth}) exceeds the maximum allowed level of ${maxDepth}.`
     return [
-      { message: context.rule.message }
+      { message }
     ]
   }
 }

package/functions/apq-path-param-query-conflict.js

@@ -1,9 +1,7 @@
 /**
- * Validates that path parameters don't appear as query parameters
- * This prevents ambiguity and design issues
  *
- * @param {object} given - The paths object
- * @param {object} options - Function options
+ * @param {object} given - The paths object ($.paths)
+ * @param {object} options - Function options (unused)
  * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
  */
 module.exports = (given, options, context) => {
@@ -26,27 +24,25 @@ module.exports = (given, options, context) => {
         continue;
       }
 
-      const parameters = operation.parameters || [];
-
+      const parameters = operation.parameters;
       if (!Array.isArray(parameters)) {
         continue;
       }
 
-      const hasPathOrQueryParams = parameters.some(
-        param => param && (param.in === 'path' || param.in === 'query')
-      );
-
-      if (!hasPathOrQueryParams) {
+      const responses = operation.responses || {};
+      const has400 = Boolean(responses['400']);
+      if (has400) {
         continue;
       }
 
-      const responses = operation.responses || {};
-      if (!responses['400']) {
-        errors.push({
-          message: `OAR069: Any param in PATH or QUERY, should have bad request (400) response.`,
-          path: [...context.path, pathKey, operationKey, 'responses']
-        });
-      }
+      parameters.forEach((param, index) => {
+        if (param && (param.in === 'path' || param.in === 'query')) {
+          errors.push({
+            message: context.rule.message,
+            path: [...context.path, pathKey, operationKey, 'parameters', index]
+          });
+        }
+      });
     }
   }
 

package/functions/apq-schema-format.js

@@ -15,6 +15,7 @@ function isValidPattern(pattern) {
 
 module.exports = (targetVal, _options, context) => {
   const typePath = [...context.path, 'type'];
+
   const format = targetVal.format;
   if (format !== undefined && format !== null) {
     if (!VALID_FORMATS.has(String(format).toLowerCase())) {
@@ -23,6 +24,11 @@ module.exports = (targetVal, _options, context) => {
     return [];
   }
 
+  const enumValues = targetVal.enum;
+  if (Array.isArray(enumValues) && enumValues.length > 0) {
+    return [];
+  }
+
   const pattern = targetVal.pattern;
   if (pattern !== undefined && pattern !== null && String(pattern).length > 0 && isValidPattern(String(pattern))) {
     return [];

package/functions/apq-security-required-response.js

@@ -1,7 +1,6 @@
 /**
- * Validates that operations with security defined include a 401 Unauthorized response
- * @param {object} given - The operation node
- * @param {object} options - Function options
+ * @param {object} given - The operation node ($.paths[*][*])
+ * @param {object} options - Function options ({ 'expected-codes': '401' | '403' | '401,403' | ... })
  * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
  */
 module.exports = (given, options, context) => {
@@ -16,6 +15,11 @@ module.exports = (given, options, context) => {
     return results;
   }
 
+  const raw = (options && options['expected-codes']) || '401';
+  const expectedCodes = (Array.isArray(raw) ? raw : String(raw).split(','))
+    .map((code) => String(code).trim())
+    .filter(Boolean);
+
   // Check if this operation has security defined
   const operationHasSecurity = given.security &&
     Array.isArray(given.security) &&
@@ -32,15 +36,22 @@ module.exports = (given, options, context) => {
     // Ignore errors accessing root security
   }
 
-  // Only require 401 if security is defined (operation-level or global)
-  if (operationHasSecurity || globalHasSecurity) {
-    if (!responses['401']) {
+  if (!(operationHasSecurity || globalHasSecurity)) {
+    return results;
+  }
+
+  const ruleName = (context.rule && context.rule.name) || '';
+  const oarId = ruleName.includes(':') ? ruleName.split(':').pop() : ruleName;
+  const prefix = oarId ? `${oarId}: ` : '';
+
+  expectedCodes.forEach((code) => {
+    if (!responses[code]) {
       results.push({
-        message: context.rule.message || 'OAR035: Response code 401 must be defined for operations with security schemes defined.',
-        path: [...context.path, 'responses']
+        message: `${prefix}Response code ${code} must be defined for operations with security schemes defined.`,
+        path: [...context.path, 'responses'],
       });
     }
-  }
+  });
 
   return results;
 };

package/functions/apq-valid-openapi-version.js

@@ -1,4 +1,4 @@
-const DEFAULT_VALID_VERSIONS = '2.0,3.0.0,3.0.1,3.0.2,3.0.3,3.1.0';
+const DEFAULT_VALID_VERSIONS = '2.0,3.0.0,3.0.1,3.0.2,3.0.3,3.1.0,3.2.0';
 
 /**
  * @param {string} targetVal

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "api-quality-spectral-ruleset",
-  "version": "1.4.0",
+  "version": "1.4.1-beta.2",
   "description": "Spectral ruleset by API Quality",
   "main": "apq-spectral.yaml",
   "files": [
@@ -25,10 +25,10 @@
     "url": "https://github.com/apiaddicts/apquality-spectral"
   },
   "devDependencies": {
-    "@stoplight/spectral-core": "^1.19.5",
-    "@stoplight/spectral-functions": "^1.9.0",
-    "@stoplight/spectral-ruleset-migrator": "^1.10.0",
-    "@stoplight/spectral-rulesets": "^1.20.2",
+    "@stoplight/spectral-core": "1.23.0",
+    "@stoplight/spectral-functions": "^1.10.5",
+    "@stoplight/spectral-ruleset-migrator": "^1.12.1",
+    "@stoplight/spectral-rulesets": "1.22.2",
     "@types/jest": "^29.5.14",
     "coverage-badges-cli": "^2.1.0",
     "jest": "^29.7.0"