api-quality-spectral-ruleset 1.4.0-beta.5 → 1.4.0

package/apq-spectral.yaml

@@ -18,6 +18,8 @@ functions:
   - apq-path-depth
   - apq-forbidden-characters
   - apq-valid-response-schema
+  - apq-valid-openapi-version
+  - apq-collection-query-param-required
   - apq-path-param-query-conflict
   - apq-schema-format
   - apq-security-required-response
@@ -69,6 +71,8 @@ rules:
     given: "$.x-wso2-security.apim.x-wso2-scopes[*].roles"
     then:
       function: apq-forbidden-characters
+      functionOptions:
+        pattern: "^[a-zA-Z0-9_\\-., ]+$"
   apiq:OAR005:
     description: "A wrong scope may cause problems to import the API definition into WSO2 or allow all users to call the endpoint."
     message: "OAR005: Scope in the operation must be defined correctly and match an existing scope."
@@ -169,7 +173,8 @@ rules:
     then:
       function: apq-path-depth
       functionOptions:
-        maxDepth: 3
+        min-level: 4
+        max-level: 5
         ignoreSegments:
           - me
   apiq:OAR015:
@@ -274,54 +279,31 @@ rules:
           ;options:.*
   apiq:OAR019:
     description: "$select must be defined as a query parameter in collection operations (excluding detail endpoints and health checks)."
-    message: "OAR019: $select must be defined as a query parameter in this operation."
+    message: "{{error}}"
     severity: warn
-    given: "$.paths[?(!@property.match(/\\/me(\\/|$)/) && !@property.match(/\\/\\{[^}]+\\}$/) && !@property.match(/status|health|ping/))].get.parameters"
+    given: "$.paths"
     then:
-      field: "$[?(@.name == '$select' && @.in == 'query')]"
-      function: truthy
+      function: apq-collection-query-param-required
+      functionOptions:
+        parameter-name: "$select"
   apiq:OAR020:
     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."
+    message: "{{error}}"
     severity: warn
-    given: "$.paths[?(!@property.match(/\\/me(\\/|$)/) && !@property.match(/\\/\\{[^}]+\\}$/) && !@property.match(/status|health|ping/))].get"
+    given: "$.paths"
     then:
-      function: schema
+      function: apq-collection-query-param-required
       functionOptions:
-        schema:
-          required: ["parameters"]
-          properties:
-            parameters:
-              type: array
-              contains:
-                type: object
-                properties:
-                  name:
-                    const: "$expand"
-                  in:
-                    const: query
-                required: [name, in]
+        parameter-name: "$expand"
   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."
+    message: "{{error}}"
     severity: warn
-    given: "$.paths[?(!@property.match(/\\/me(\\/|$)/) && !@property.match(/\\/\\{[^}]+\\}$/) && !@property.match(/status|health|ping/))].get"
+    given: "$.paths"
     then:
-      function: schema
+      function: apq-collection-query-param-required
       functionOptions:
-        schema:
-          required: ["parameters"]
-          properties:
-            parameters:
-              type: array
-              contains:
-                type: object
-                properties:
-                  name:
-                    const: "$exclude"
-                  in:
-                    const: query
-                required: [name, in]
+        parameter-name: "$exclude"
   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."
@@ -537,11 +519,15 @@ rules:
       function: apq-schema-format
   apiq:OAR038:
     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}}'."
+    message: "{{error}}"
     severity: error
-    given: "$.paths.*.post.responses.*.content..schema.properties"
+    given:
+      - "$.paths.*.post.responses.*.content..schema.properties"
+      - "$.paths.*.post.responses.*.schema.properties"
     then:
       function: apq-valid-response-schema
+      functionOptions:
+        data-property: data
   apiq:OAR039:
     description: "Response codes must be defined according to the standard depending on the HTTP verb and resource path."
     message: "{{error}}"
@@ -580,13 +566,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 must follow the 'apfc_sc_' prefix standard."
+    message: "OAR040: Scope name value is non compliant with the standard."
     severity: "error"
     given: "$.x-wso2-security.apim.x-wso2-scopes[*].name"
     then:
       function: pattern
       functionOptions:
-        match: "^apfc_sc_.*"
+        match: "^[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."
@@ -1021,7 +1007,7 @@ rules:
       function: apq-password-format
   apiq:OAR082:
     description: "The string properties 'product', 'line', and 'price' must define a byte or binary format."
-    message: "OAR082: Property '{{property}}' must define a 'byte' or 'binary' format (currently: {{format}})."
+    message: "{{error}}"
     severity: error
     given: "$..[?(@.properties)]"
     then:
@@ -1050,13 +1036,15 @@ rules:
         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."
-    message: "OAR085: The OpenAPI version '{{value}}' is not allowed. Allowed versions: 2.0, 3.0.0, 3.0.1, 3.0.2, 3.0.3, 3.1.0."
+    message: "{{error}}"
     severity: warn
-    given: "$.openapi"
+    given:
+      - "$.openapi"
+      - "$.swagger"
     then:
-      function: pattern
+      function: apq-valid-openapi-version
       functionOptions:
-        match: "^(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"
   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."

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

@@ -23,14 +23,11 @@ module.exports = (schema, options = {}, context) => {
       return;
     }
 
-    // Check if format is byte or binary
     const format = propSchema.format || '';
-    if (format && format !== 'byte' && format !== 'binary') {
+    if (format !== 'byte' && format !== 'binary') {
       results.push({
-        message: context.rule.message
-          .replace('{{property}}', propName)
-          .replace('{{format}}', format || 'undefined'),
-        path: [...context.path, 'properties', propName],
+        message: `OAR082: Property '${propName}' must define a 'byte' or 'binary' format (currently: ${format || 'missing'}).`,
+        path: [...context.path, 'properties', propName, 'type'],
       });
     }
   });

package/functions/apq-collection-query-param-required.js

@@ -0,0 +1,69 @@
+
+const DEFAULT_PATHS = '/me;/health;/ping;/status';
+const PATH_PARAM_SUFFIX_REGEX = /\/\{[^}]+\}$/;
+const STRATEGY_INCLUDE = 'Include';
+const STRATEGY_EXCLUDE = 'Exclude';
+
+const escapeRegExp = (segment) => segment.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+
+const parsePathPatterns = (paths) => paths
+  .split(/[\n;]/)
+  .map((p) => p.trim())
+  .filter(Boolean)
+  .map((segment) => new RegExp(`${escapeRegExp(segment)}(/|$)`));
+
+const shouldIncludePath = (path, patterns, strategy) => {
+  const matchesList = patterns.some((regex) => regex.test(path));
+  return strategy === STRATEGY_INCLUDE ? matchesList : !matchesList;
+};
+
+const hasQueryParameter = (parameters, parameterName) => Array.isArray(parameters)
+  && parameters.some((p) => p && !p.$ref && p.name === parameterName && p.in === 'query');
+
+/**
+ * @param {object} given
+ * @param {object} options
+ * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
+ */
+module.exports = (given, options = {}, context) => {
+  if (!given || typeof given !== 'object') return [];
+
+  const ruleCode = context && context.rule && context.rule.name ? context.rule.name.split(':').pop() : 'apq-collection-query-param-required';
+
+  const parameterName = options['parameter-name'];
+  if (!parameterName) {
+    return [{
+      message: `${ruleCode}: "parameter-name" functionOption is required.`,
+      path: context.path,
+    }];
+  }
+
+  const strategy = options.pathValidationStrategy === STRATEGY_INCLUDE
+    ? STRATEGY_INCLUDE
+    : STRATEGY_EXCLUDE;
+
+  const rawPaths = typeof options.paths === 'string' ? options.paths : DEFAULT_PATHS;
+  const patterns = parsePathPatterns(rawPaths);
+
+  const results = [];
+
+  Object.entries(given).forEach(([path, pathItem]) => {
+    if (!pathItem || typeof pathItem !== 'object') return;
+
+    const getOperation = pathItem.get;
+    if (!getOperation || typeof getOperation !== 'object') return;
+
+    if (PATH_PARAM_SUFFIX_REGEX.test(path)) return;
+    if (!shouldIncludePath(path, patterns, strategy)) return;
+
+    if (!hasQueryParameter(getOperation.parameters, parameterName)) {
+      results.push({
+        message: `${ruleCode}: ${parameterName} must be defined as a query parameter in this operation.`,
+        path: [...context.path, path, 'get'],
+      });
+    }
+  });
+
+  return results;
+};

package/functions/apq-forbidden-characters.js

@@ -3,8 +3,8 @@
  * @param {object} options
  * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
  */
-module.exports = (targetVal, _options, context) => {
-  const pattern = /^[a-zA-Z0-9_\-., ]+$/;
+module.exports = (targetVal, options, context) => {
+  const pattern = new RegExp((options && options.pattern) || '^[a-zA-Z0-9_\\-., ]+$');
   const errors = [];
   const basePath = context.path || [];
 

package/functions/apq-path-depth.js

@@ -4,7 +4,8 @@
  * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
  */
 module.exports = (targetVal, options, context) => {
-  const maxDepth = options.maxDepth ?? 3
+  const minDepth = options['min-level'] ?? options.minDepth ?? null
+  const maxDepth = options['max-level'] ?? options.maxDepth ?? 3
   const ignore = options.ignoreSegments ?? []
   const segments = targetVal
     .split('/')
@@ -14,7 +15,11 @@ module.exports = (targetVal, options, context) => {
 
   const depth = segments.length;
 
-  if (depth > maxDepth) {
+  const isOutOfRange = minDepth != null
+    ? (depth >= minDepth && depth <= maxDepth)
+    : depth > maxDepth
+
+  if (isOutOfRange) {
     return [
       { message: context.rule.message }
     ]

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

@@ -0,0 +1,20 @@
+const DEFAULT_VALID_VERSIONS = '2.0,3.0.0,3.0.1,3.0.2,3.0.3,3.1.0';
+
+/**
+ * @param {string} targetVal
+ * @param {object} options
+ */
+module.exports = (targetVal, options) => {
+  const raw = (options && options['valid-versions']) || DEFAULT_VALID_VERSIONS;
+  const validVersions = (Array.isArray(raw) ? raw : String(raw).split(','))
+    .map(version => String(version).trim())
+    .filter(Boolean);
+
+  if (!validVersions.includes(String(targetVal))) {
+    return [
+      {
+        message: `OAR085: The OpenAPI version '${targetVal}' is not allowed. Allowed versions: ${validVersions.join(', ')}.`
+      }
+    ];
+  }
+};

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

@@ -1,11 +1,12 @@
 /**
  * @param {object} targetVal
- * @param {object} _options
+ * @param {object} options
  * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
  */
-module.exports = (targetVal, _options, context) => {
+module.exports = (targetVal, options, context) => {
   const errors = [];
-  const VALID_NAMES = ['data', 'error'];
+  const dataProperty = (options && options['data-property']) || 'data';
+  const VALID_NAMES = [dataProperty, 'error'];
 
   if (!targetVal || typeof targetVal !== 'object') {
     return errors;
@@ -20,8 +21,8 @@ module.exports = (targetVal, _options, context) => {
   for (const [propName, propValue] of Object.entries(targetVal)) {
     if (!VALID_NAMES.includes(propName)) {
       errors.push({
-        message: context.rule.message,
-        path: [propName]
+        message: `OAR038: Response property must be named '${dataProperty}' or 'error'. Got '${propName}'.`,
+        path: [...path, propName]
       });
     } else {
       const subProps = propValue && propValue.properties;
@@ -29,7 +30,7 @@ module.exports = (targetVal, _options, context) => {
       if (!hasSubProps) {
         errors.push({
           message: `OAR038: Property '${propName}' must have at least one sub-property.`,
-          path: [propName]
+          path: [...path, propName]
         });
       }
     }

package/package.json

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