api-quality-spectral-ruleset 1.4.1 → 1.5.0-beta.1

package/apq-spectral.yaml

@@ -30,6 +30,8 @@ functions:
   - apq-status-endpoint-check
   - apq-validate-structure
   - apq-numeric-parameter-integrity
+  - apq-wso2-scopes-valid
+  - apq-numeric-path-param
 extends:
   - spectral:asyncapi
   - spectral:oas
@@ -46,14 +48,12 @@ rules:
         match: "^https://"
   apiq:OAR002:
     description: "A wrong scope definition may cause problems to import the API definition into WSO2."
-    message: "OAR002: Scope definition must include the 'key' attribute along with 'name' and 'roles'."
+    message: "{{error}}"
     documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR002.md"
     severity: "error"
-    given: "$.x-wso2-security.apim.x-wso2-scopes[*]"
+    given: "$.x-wso2-security.apim.x-wso2-scopes"
     then:
-      - function: "truthy"
-        field: "key"
-        message: "Scope must define a 'key' attribute."
+      function: apq-wso2-scopes-valid
   apiq:OAR003:
     description: "A description can help other developers to understand the correct use of the scope."
     message: "OAR003: Scope must define a 'description' attribute."
@@ -194,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' || (@.type && @.type.indexOf && (@.type.indexOf('number') > -1 || @.type.indexOf('integer') > -1))))]"
     then:
       function: schema
       functionOptions:
@@ -485,7 +485,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)]"
     then:
       function: apq-schema-format
   apiq:OAR038:
@@ -686,7 +686,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' || (@.type && @.type.indexOf && (@.type.indexOf('integer') > -1 || @.type.indexOf('number') > -1))))]"
     then:
       field: format
       function: truthy
@@ -836,10 +836,7 @@ rules:
     severity: error
     given: "$.paths[*][get,post,put,patch,delete].parameters[?(@.in == 'path')]"
     then:
-      field: "schema.type"
-      function: pattern
-      functionOptions:
-        match: "^(?!integer|number)"
+      function: apq-numeric-path-param
   apiq:OAR071:
     description: "Query parameters 'param1', 'param2', and 'param3' must be defined in the operation."
     message: "OAR071: Query parameters 'param1', 'param2', and 'param3' must be defined."
@@ -876,15 +873,15 @@ rules:
     severity: error
     resolved: false
     given:
-      - "$..[?(@ && @.in && @.schema && (@.schema.type == 'integer' || @.schema.type == 'number'))].schema"
-      - "$..[?(@ && @.in && (@.type == 'integer' || @.type == 'number'))]"
+      - "$..[?(@ && @.in && @.schema && (@.schema.type == 'integer' || @.schema.type == 'number' || (@.schema.type && @.schema.type.indexOf && (@.schema.type.indexOf('integer') > -1 || @.schema.type.indexOf('number') > -1))))].schema"
+      - "$..[?(@ && @.in && (@.type == 'integer' || @.type == 'number' || (@.type && @.type.indexOf && (@.type.indexOf('integer') > -1 || @.type.indexOf('number') > -1))))]"
     then:
       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 && @.schema.type == 'string' && @.in == 'path')]"
+    given: "$.paths[*][get,post,put,patch,delete].parameters[?(@ && @.schema && (@.schema.type == 'string' || (@.schema.type && @.schema.type.indexOf && @.schema.type.indexOf('string') > -1)) && @.in == 'path')]"
     then:
       function: schema
       functionOptions:
@@ -902,7 +899,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' || (@.type && @.type.indexOf && (@.type.indexOf('number') > -1 || @.type.indexOf('integer') > -1))))]"
     then:
       function: schema
       functionOptions:
@@ -1000,7 +997,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, 3.2.0."
+    description: "The OpenAPI version must be one of: 2.0, 3.0.0, 3.0.1, 3.0.2, 3.0.3, 3.0.4, 3.1.0, 3.1.1, 3.1.2, 3.2.0."
     message: "{{error}}"
     severity: warn
     given:
@@ -1009,7 +1006,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,3.2.0"
+        valid-versions: "2.0,3.0.0,3.0.1,3.0.2,3.0.3,3.0.4,3.1.0,3.1.1,3.1.2,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."

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

@@ -5,7 +5,6 @@ module.exports = (schema, options = {}, context) => {
     return results;
   }
 
-  // Fields that must have byte or binary format
   const fieldsToCheck = (options['fields-to-apply'] || 'product,line,price')
     .split(',')
     .map(f => f.trim().toLowerCase());
@@ -13,7 +12,6 @@ module.exports = (schema, options = {}, context) => {
   const properties = schema.properties || {};
 
   Object.entries(properties).forEach(([propName, propSchema]) => {
-    // Only check if this property is in our list
     if (!fieldsToCheck.includes(propName.toLowerCase())) {
       return;
     }
@@ -22,13 +20,17 @@ module.exports = (schema, options = {}, context) => {
       return;
     }
 
-    // Check if it's a string type
-    if (propSchema.type !== 'string') {
+    const type = propSchema.type;
+    const isStringType = type === 'string' || (Array.isArray(type) && type.includes('string'));
+    if (!isStringType) {
       return;
     }
 
     const format = propSchema.format || '';
-    if (format !== 'byte' && format !== 'binary') {
+    const hasBinaryFormat = format === 'byte' || format === 'binary';
+    const hasContentEncoding = propSchema.contentEncoding !== undefined
+      || propSchema.contentMediaType !== undefined;
+    if (!hasBinaryFormat && !hasContentEncoding) {
       results.push({
         message: `OAR082: Property '${propName}' must define a 'byte' or 'binary' format (currently: ${format || 'missing'}).`,
         path: [...context.path, 'properties', propName, 'type'],

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

@@ -9,7 +9,9 @@ module.exports = (node, options, context) => {
   if (!node || typeof node !== 'object') return results;
 
   const { type } = node;
-  if (type !== 'integer' && type !== 'number') return results;
+  const types = Array.isArray(type) ? type : [type];
+  const isNumeric = types.indexOf('integer') > -1 || types.indexOf('number') > -1;
+  if (!isNumeric) return results;
 
   const has = (field) => Object.prototype.hasOwnProperty.call(node, field);
   const hasMin = has('minimum');

package/functions/apq-numeric-path-param.js

@@ -0,0 +1,34 @@
+/**
+ * @param {object} param   the parameter object (given selects params with `in: path`)
+ * @param {object} options
+ * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
+ */
+module.exports = (param, options, context) => {
+  const results = [];
+  if (!param || typeof param !== 'object' || param.in !== 'path') return results;
+
+  let typeVal;
+  let typePath;
+  if (param.schema && param.schema.type !== undefined) {
+    typeVal = param.schema.type;
+    typePath = [...context.path, 'schema', 'type'];
+  } else if (param.type !== undefined) {
+    typeVal = param.type;
+    typePath = [...context.path, 'type'];
+  } else {
+    return results;
+  }
+
+  const types = Array.isArray(typeVal) ? typeVal : [typeVal];
+  const isNumeric = types.indexOf('integer') > -1
+    || types.indexOf('number') > -1
+    || types.indexOf('float') > -1;
+  if (!isNumeric) return results;
+
+  const ruleCode = context.rule.name.split(':').pop();
+  results.push({
+    message: `${ruleCode}: Parameters in path should not be numeric.`,
+    path: typePath,
+  });
+  return results;
+};

package/functions/apq-required-fields-exist.js

@@ -6,7 +6,10 @@
 module.exports = (given, options, context) => {
   const results = [];
 
-  if (!given || given.type !== 'object') return results;
+  if (!given) return results;
+  const t = given.type;
+  const isObjectType = t === 'object' || (Array.isArray(t) && t.indexOf('object') > -1);
+  if (!isObjectType) return results;
 
   const { required, properties } = given;
   if (!Array.isArray(required)) return results;

package/functions/apq-schema-format.js

@@ -16,6 +16,12 @@ function isValidPattern(pattern) {
 module.exports = (targetVal, _options, context) => {
   const typePath = [...context.path, 'type'];
 
+  const type = targetVal.type;
+  const isStringType = type === 'string' || (Array.isArray(type) && type.includes('string'));
+  if (!isStringType) {
+    return [];
+  }
+
   const format = targetVal.format;
   if (format !== undefined && format !== null) {
     if (!VALID_FORMATS.has(String(format).toLowerCase())) {

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,3.2.0';
+const DEFAULT_VALID_VERSIONS = '2.0,3.0.0,3.0.1,3.0.2,3.0.3,3.0.4,3.1.0,3.1.1,3.1.2,3.2.0';
 
 /**
  * @param {string} targetVal

package/functions/apq-wso2-scopes-valid.js

@@ -0,0 +1,58 @@
+/**
+ * @param {*} targetVal the `x-wso2-scopes` container node value
+ * @param {object} _options unused
+ * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
+ */
+const DEFINITION_WRONG = "OAR002: WSO2 scopes definition is wrong";
+const REQUIRED_PROP = "OAR002: WSO2 scope '{0}' is required";
+const REQUIRED_PROPERTIES = ['name', 'key', 'roles'];
+
+const requiredMessage = (prop) => REQUIRED_PROP.replace('{0}', prop);
+
+// A scope property counts as "required but missing" when it is absent, null, a
+// blank string, or an empty collection ([] / {}) — mirrors Sonar's OAR002 check.
+const isEmptyValue = (value) =>
+  value === null
+  || (typeof value === 'string' && value.trim() === '')
+  || (Array.isArray(value) && value.length === 0)
+  || (typeof value === 'object' && !Array.isArray(value) && Object.keys(value).length === 0);
+
+module.exports = (targetVal, _options, context) => {
+  const errors = [];
+  const basePath = context.path || [];
+
+  if (targetVal === null || typeof targetVal !== 'object') {
+    errors.push({ message: DEFINITION_WRONG, path: basePath });
+    return errors;
+  }
+
+  const entries = Array.isArray(targetVal)
+    ? targetVal.map((scope, index) => [index, scope])
+    : Object.keys(targetVal).map((key) => [key, targetVal[key]]);
+
+  if (entries.length === 0) {
+    errors.push({ message: DEFINITION_WRONG, path: basePath });
+    return errors;
+  }
+
+  entries.forEach(([key, scope]) => {
+    const scopePath = [...basePath, key];
+
+    if (scope === null || typeof scope !== 'object' || Array.isArray(scope)) {
+      REQUIRED_PROPERTIES.forEach((prop) => {
+        errors.push({ message: requiredMessage(prop), path: scopePath });
+      });
+      return;
+    }
+
+    REQUIRED_PROPERTIES.forEach((prop) => {
+      if (!Object.prototype.hasOwnProperty.call(scope, prop)) {
+        errors.push({ message: requiredMessage(prop), path: scopePath });
+      } else if (isEmptyValue(scope[prop])) {
+        errors.push({ message: requiredMessage(prop), path: [...scopePath, prop] });
+      }
+    });
+  });
+
+  return errors;
+};

package/package.json

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