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

package/apq-spectral.yaml

@@ -18,8 +18,11 @@ functions:
   - apq-path-depth
   - apq-forbidden-characters
   - apq-valid-response-schema
+  - apq-post-201-location-header
+  - apq-response-no-content
   - apq-valid-openapi-version
   - apq-collection-query-param-required
+  - apq-total-param-default-value
   - apq-path-param-query-conflict
   - apq-schema-format
   - apq-security-required-response
@@ -45,6 +48,11 @@ functions:
   - apq-mandatory-response-codes
   - apq-rate-limit-response
   - apq-forbidden-query-format
+  - apq-wso2-scope-defined
+  - apq-undefined-response-media-type
+  - apq-wso2-auth-type-required
+  - apq-response-content-required
+  - apq-tags-consistency
 extends:
   - spectral:asyncapi
   - spectral:oas
@@ -89,17 +97,13 @@ rules:
         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."
+    message: "{{error}}"
+    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR005.md"
     severity: "error"
-    given: "$.paths[*][*].x-scope"
+    resolved: false
+    given: "$"
     then:
-      - function: "truthy"
-        message: "Scope must be defined in the operation."
-      - function: enumeration
-        functionOptions:
-          values:
-            - read
-            - write
+      function: apq-wso2-scope-defined
   apiq:OAR006:
     description: "Routes must define request media types supported by the API."
     message: "OAR006: Specify at least one Media Type in the content of the request body."
@@ -116,10 +120,13 @@ rules:
     message: "OAR007: Specify at least one Media Type in the content of the response body."
     documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR007.md"
     severity: "error"
-    given: "$.paths[*][get,post,put,patch,delete].responses[?(@property != '204')]"
+    given:
+      - "$.paths[*][post,put,patch]"
+      - "$.webhooks[*][post,put,patch]"
+      - "$.paths[*][get,post,put,patch,delete].responses[?(@property != '204')]"
+      - "$.webhooks[*][get,post,put,patch,delete].responses[?(@property != '204')]"
     then:
-      - field: "content"
-        function: truthy
+      function: apq-undefined-response-media-type
   apiq:OAR008:
     description: "HTTP verbs not encouraged."
     message: "{{error}}"
@@ -142,7 +149,13 @@ rules:
     description: "Default response media type should be defined for responses."
     message: "OAR010: Default response media type is mandatory."
     severity: warn
-    given: "$.paths[*][get,post,put,patch,delete]"
+    given:
+      - "$.paths[*][post,put,patch]"
+      - "$.webhooks[*][post,put,patch]"
+      - "$.paths[*][get,post,put,patch,delete].responses[?(@property != '204')]"
+      - "$.webhooks[*][get,post,put,patch,delete].responses[?(@property != '204')]"
+      - "$.paths[*][get,post,put,patch,delete].responses[?(@property != '204')].content"
+      - "$.webhooks[*][get,post,put,patch,delete].responses[?(@property != '204')].content"
     then:
       function: apq-response-media-type
       functionOptions:
@@ -350,20 +363,18 @@ rules:
         pathValidationStrategy: "/include"
   apiq:OAR026:
     description: "The $total parameter default value should be false."
-    message: "OAR026: The $total parameter default value should be false."
+    message: "{{error}}"
     severity: error
     given: "$.paths[*].get.parameters[?(@.name == '$total' && @.in == 'query')]"
     then:
-      field: "schema.default"
-      function: falsy
+      function: apq-total-param-default-value
   apiq:OAR027:
     description: "Location header is required in responses with code 201 from POST operations."
-    message: "OAR027: Location header is required in responses with code 201 from POST operations."
+    message: "{{error}}"
     severity: error
     given: "$.paths.*.post.responses['201']"
     then:
-      field: "headers.Location.schema.type"
-      function: truthy
+      function: apq-post-201-location-header
   apiq:OAR028:
     description: "$filter must be defined as a query parameter in the collection GET operations selected by the configured paths."
     message: "{{error}}"
@@ -471,9 +482,7 @@ rules:
     description: "The 201 response schema of a POST operation must have properties named 'data' or 'error' with at least one sub-property."
     message: "{{error}}"
     severity: error
-    given:
-      - "$.paths.*.post.responses.*.content..schema.properties"
-      - "$.paths.*.post.responses.*.schema.properties"
+    given: "$.paths.*.post.responses['201']"
     then:
       function: apq-valid-response-schema
       functionOptions:
@@ -524,13 +533,14 @@ rules:
       functionOptions:
         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."
+    description: "A WSO2 x-scope on an operation always requires an x-auth-type definition."
+    message: "{{error}}"
+    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR041.md"
     severity: "error"
-    given: "$.paths[*].get"
+    resolved: false
+    given: "$"
     then:
-      field: "x-aut-type"
-      function: truthy
+      function: apq-wso2-auth-type-required
   apiq:OAR042:
     description: "Base path must be compliant with the standard."
     message: "OAR042: Base path must follow the '/api-<name>/v<version>' standard."
@@ -545,12 +555,19 @@ rules:
   apiq:OAR043:
     description: "OpenAPI definition contains structural errors that would be detected by a strict parser or validator."
     message: "{{error}}"
+    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR043.md"
     severity: error
     given:
       - $.paths.*.*.parameters.*.in
       - $.components.parameters.*.in
+      - $.paths.*.*.parameters.*.type
+      - $.components.parameters.*.type
       - $.paths.*.*.parameters.*.schema.type
       - $.components.parameters.*.schema.type
+      - $.webhooks.*.*.parameters.*.in
+      - $.webhooks.*.*.parameters.*.schema.type
+      - $.components.pathItems.*.*.parameters.*.in
+      - $.components.pathItems.*.*.parameters.*.schema.type
     then:
       function: apq-validate-structure
   apiq:OAR044:
@@ -575,8 +592,7 @@ rules:
     severity: error
     given: "$.paths[*][get,post,put,patch,delete].responses[?(@property !== '204')]"
     then:
-      field: "content"
-      function: truthy
+      function: apq-response-content-required
   apiq:OAR046:
     description: "Each operation SHOULD have a tag."
     message: "OAR046: You should categorize the operations of your contract with tags."
@@ -598,29 +614,12 @@ rules:
               type: array
               minItems: 1
   apiq:OAR047:
-    description: "Tags required and each tag must have a short description."
-    message: "OAR047: Add tags with a short description to each one."
+    description: "Tags required and each tag must have a short description, must not be duplicated, and every tag used by an operation must be declared at the top level."
+    message: "{{error}}"
     severity: error
     given: "$"
     then:
-      - field: "tags"
-        function: schema
-        functionOptions:
-          schema:
-            type: array
-            minLength: 1
-            items:
-              type: object
-              required:
-                - name
-                - description
-              properties:
-                name:
-                  type: string
-                  minLength: 1
-                description:
-                  type: string
-                  minLength: 1
+      function: apq-tags-consistency
   apiq:OAR048:
     description: APIs must define at most one body parameter.
     message: "OAR048: An operation can have at most one body parameter"
@@ -634,12 +633,11 @@ rules:
       function: apq-at-most-one-body-parameter
   apiq:OAR049:
     description: "204 No Content MUST NOT return any content."
-    message: "OAR049: 204 No Content MUST NOT return any content."
+    message: "{{error}}"
     severity: error
     given: "$.paths[*][get,post,put,patch,delete].responses['204']"
     then:
-      field: "content"
-      function: falsy
+      function: apq-response-no-content
   apiq:OAR050:
     description: "Provide a summary for each operation."
     message: "OAR050: Provide a summary for each operation."
@@ -650,7 +648,7 @@ rules:
       function: truthy
   apiq:OAR051:
     description: "Summary and description must be different - not just case variations or semantic duplicates."
-    message: "OAR051: Summary and description must be meaningfully different from each other."
+    message: "{{error}}"
     severity: "error"
     given: "$.paths[*][get,post,put,patch,delete]"
     then:
@@ -875,7 +873,9 @@ rules:
     description: "All parameters in query must be snake_case."
     message: "OAR077: All parameters in query must be snake_case."
     severity: warn
-    given: "$.paths[*][*].parameters[?(@.in == 'query')]"
+    given:
+      - "$.paths[*][*].parameters[?(@.in == 'query')]"
+      - "$.paths[*].parameters[?(@.in == 'query')]"
     then:
       field: "name"
       function: pattern
@@ -940,7 +940,9 @@ rules:
     description: "Some formats should not pass through this querystring."
     message: "{{error}}"
     severity: error
-    given: "$.paths[*][get,post,put,patch,delete].parameters[?(@.in == 'query')]"
+    given:
+      - "$.paths[*][get,post,put,patch,delete].parameters[?(@.in == 'query')]"
+      - "$.paths[*].parameters[?(@.in == 'query')]"
     then:
       function: apq-forbidden-query-format
       functionOptions:

package/functions/apq-check-examples-coverage.js

@@ -1,15 +1,13 @@
 const COMBINERS = ['allOf', 'oneOf', 'anyOf'];
 
-// A level is validated unless explicitly turned off with `false`.
+const typeIncludes = (type, name) => (Array.isArray(type) ? type.includes(name) : type === name);
+
 const isOn = (value) => value !== false;
 
-// Whole-body (root) example declared directly on a schema node.
 const schemaHasRootExample = (schema) =>
   !!schema && typeof schema === 'object'
   && (schema.example !== undefined || schema.examples !== undefined);
 
-// Parameter-level example: param.example/examples, the param schema's root example,
-// or a media-type example under param.content (OAS3). OAS2 params use param.example.
 const hasParameterExample = (param) => {
   if (!param || typeof param !== 'object') return false;
   if (param.example !== undefined || param.examples !== undefined) return true;
@@ -23,9 +21,6 @@ const hasParameterExample = (param) => {
   return false;
 };
 
-// Body-level (whole response / requestBody) example: a media-type example/examples or a
-// root schema example. OAS3 -> content.<mt>.{example|examples|schema.example}.
-// OAS2 -> node.examples map or node.schema root example.
 const hasBodyLevelExample = (node) => {
   if (!node || typeof node !== 'object') return false;
   if (node.content && typeof node.content === 'object') {
@@ -34,16 +29,15 @@ const hasBodyLevelExample = (node) => {
         && (mt.example !== undefined || mt.examples !== undefined || schemaHasRootExample(mt.schema)),
     );
   }
-  if (node.examples !== undefined) return true; // OAS2 response-level examples map
-  if (schemaHasRootExample(node.schema)) return true; // OAS2 root schema example
+  if (node.examples !== undefined) return true;
+  if (schemaHasRootExample(node.schema)) return true;
   return false;
 };
 
-// Per-leaf-property example check (recurses objects, arrays and combiners).
 const collectPropertyIssues = (schema, issues, basePath) => {
   if (!schema || typeof schema !== 'object' || schema.$ref) return;
 
-  if (schema.type === 'array') {
+  if (typeIncludes(schema.type, 'array')) {
     if (schema.items) collectPropertyIssues(schema.items, issues, [...basePath, 'items']);
     return;
   }
@@ -53,7 +47,7 @@ const collectPropertyIssues = (schema, issues, basePath) => {
       if (!propSchema || typeof propSchema !== 'object' || propSchema.$ref) continue;
       const propPath = [...basePath, 'properties', propName];
       const propType = propSchema.type;
-      if (propType === 'object' || propType === 'array' || (!propType && propSchema.properties)) {
+      if (typeIncludes(propType, 'object') || typeIncludes(propType, 'array') || (!propType && propSchema.properties)) {
         collectPropertyIssues(propSchema, issues, propPath);
       } else if (propType !== undefined && propSchema.example === undefined && propSchema.examples === undefined) {
         issues.push({
@@ -71,7 +65,6 @@ const collectPropertyIssues = (schema, issues, basePath) => {
   });
 };
 
-// Property-level coverage for a response / requestBody node (OAS3 content.* or OAS2 schema).
 const collectBodyProperties = (node, issues, basePath) => {
   if (node.content && typeof node.content === 'object') {
     Object.entries(node.content).forEach(([mediaType, mt]) => {
@@ -83,10 +76,6 @@ const collectBodyProperties = (node, issues, basePath) => {
 };
 
 /**
- * OAR031 — examples coverage, validated independently per level. Each level can be
- * switched off via functionOptions (all default on):
- *   validateResponse, validateRequestBody, validateParameter, validateProperty
- *
  * @param {object} given
  * @param {object} options
  * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
@@ -106,13 +95,17 @@ module.exports = function oar031ExamplesCoverage(given, options, context) {
   const isRequestBody = nodePath.at(-1) === 'requestBody';
 
   if (isParameter) {
+    const doc = context.document?.data ?? {};
+    const isOAP2 = typeof doc.swagger === 'string';
+    if (isOAP2 && given.in !== 'body') {
+      return issues;
+    }
     if (validateParameter && !hasParameterExample(given)) {
       issues.push({
         message: `OAR031: Parameter '${given.name || ''}' must have an example defined`,
         path: nodePath,
       });
     }
-    // OAS2 body parameters carry a schema, so property-level coverage applies to them too.
     if (given.in === 'body' && validateProperty && given.schema) {
       collectPropertyIssues(given.schema, issues, [...nodePath, 'schema']);
     }

package/functions/apq-compare-insensitive.js

@@ -26,12 +26,13 @@ module.exports = (given, options, context) => {
     return errors;
   }
 
-  const threshold = options.threshold || 0.6;
+  const threshold = typeof options.threshold === 'number' ? options.threshold : 0.6;
+  const baseMessage = 'OAR051: Summary and description must be meaningfully different from each other.';
 
   // Exact match (case-insensitive)
   if (propA.trim().toUpperCase() === propB.trim().toUpperCase()) {
     errors.push({
-      message: context.rule.message,
+      message: baseMessage,
       path: [...context.path, options.property]
     });
     return errors;
@@ -41,7 +42,7 @@ module.exports = (given, options, context) => {
   const similarity = calculateSimilarity(propA, propB);
   if (similarity >= threshold) {
     errors.push({
-      message: `${context.rule.message} (${Math.round(similarity * 100)}% similar)`,
+      message: `${baseMessage} (${Math.round(similarity * 100)}% similar)`,
       path: [...context.path, options.property]
     });
   }

package/functions/apq-password-format.js

@@ -4,6 +4,10 @@
  * @param {object} options - Function options
  * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
  */
+function typeIncludes(type, name) {
+  return Array.isArray(type) ? type.includes(name) : type === name;
+}
+
 module.exports = (given, options, context) => {
   const results = [];
 
@@ -17,10 +21,9 @@ module.exports = (given, options, context) => {
       return;
     }
 
-    // Check if this is a password-related field (name contains "password")
     const isPasswordField = propName.toLowerCase().includes('password');
 
-    if (isPasswordField && propSchema.type === 'string') {
+    if (isPasswordField && typeIncludes(propSchema.type, 'string')) {
       // Password fields must have format: password
       if (propSchema.format !== 'password') {
         results.push({

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

@@ -18,14 +18,16 @@ module.exports = (given, options, context) => {
       continue;
     }
 
+    const sharedParams = Array.isArray(pathItem.parameters) ? pathItem.parameters : [];
+
     for (const [operationKey, operation] of Object.entries(pathItem)) {
       if (!operation || typeof operation !== 'object' ||
           !httpMethods.includes(operationKey)) {
         continue;
       }
 
-      const parameters = operation.parameters;
-      if (!Array.isArray(parameters)) {
+      const operationParams = Array.isArray(operation.parameters) ? operation.parameters : [];
+      if (sharedParams.length === 0 && operationParams.length === 0) {
         continue;
       }
 
@@ -35,7 +37,13 @@ module.exports = (given, options, context) => {
         continue;
       }
 
-      parameters.forEach((param, index) => {
+      const overridden = new Set(
+        operationParams
+          .filter((p) => p && p.name && p.in)
+          .map((p) => `${p.in}:${p.name}`)
+      );
+
+      operationParams.forEach((param, index) => {
         if (param && (param.in === 'path' || param.in === 'query')) {
           errors.push({
             message: context.rule.message,
@@ -43,6 +51,15 @@ module.exports = (given, options, context) => {
           });
         }
       });
+
+      sharedParams.forEach((param, index) => {
+        if (!param || (param.in !== 'path' && param.in !== 'query')) return;
+        if (overridden.has(`${param.in}:${param.name}`)) return;
+        errors.push({
+          message: context.rule.message,
+          path: [...context.path, pathKey, 'parameters', index]
+        });
+      });
     }
   }
 

package/functions/apq-post-201-location-header.js

@@ -0,0 +1,36 @@
+/**
+ * @param {object} given - the 201 response object of a POST operation
+ * @param {object} options - unused
+ * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
+ */
+module.exports = (given, options, context) => {
+  if (!given || typeof given !== 'object') {
+    return [];
+  }
+
+  const doc = context.document?.data ?? {};
+  const isOAP2 = typeof doc.swagger === 'string';
+  const path = context.path || [];
+  const message = 'OAR027: Location header is required in responses with code 201 from POST operations.';
+
+  const headers = given.headers;
+  const headerKey = headers && typeof headers === 'object'
+    ? Object.keys(headers).find((key) => key.toLowerCase() === 'location')
+    : undefined;
+
+  if (!headerKey) {
+    return [{ message, path: [...path, 'headers'] }];
+  }
+
+  const header = headers[headerKey];
+  const type = isOAP2 ? header && header.type : header && header.schema && header.schema.type;
+
+  if (!type) {
+    const typePath = isOAP2
+      ? [...path, 'headers', headerKey, 'type']
+      : [...path, 'headers', headerKey, 'schema', 'type'];
+    return [{ message, path: typePath }];
+  }
+
+  return [];
+};

package/functions/apq-require-response-on-path-params.js

@@ -20,10 +20,12 @@ module.exports = (given, options, context) => {
   const shouldExclude = strategy === '/exclude' ? isListed : !isListed;
   if (shouldExclude) return [];
 
-  const pathItemKeyIndex = context.path?.length - 2;
-  const pathItem = typeof pathItemKeyIndex === 'number'
-    ? context.path?.[pathItemKeyIndex]
-    : null;
+  const pathKey = context.path[1];
+  const rawPaths = (context.document
+    && context.document.parserResult
+    && context.document.parserResult.data
+    && context.document.parserResult.data.paths) || {};
+  const pathItem = rawPaths[pathKey] || null;
 
   const pathParams = (pathItem?.parameters || []).filter(
     p => p?.in === 'path'

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

@@ -0,0 +1,24 @@
+/**
+ * @param {object} given - the response object (e.g. responses['201'])
+ * @param {object} options - unused
+ * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
+ */
+module.exports = (given, options, context) => {
+  if (!given || typeof given !== 'object') {
+    return [];
+  }
+
+  const doc = (context.document
+    && context.document.parserResult
+    && context.document.parserResult.data) || {};
+  const field = doc.swagger ? 'schema' : 'content';
+  const value = given[field];
+
+  const isEmpty = value === undefined || value === null
+    || (typeof value === 'object' && !Array.isArray(value) && Object.keys(value).length === 0);
+
+  if (isEmpty) {
+    return [{ message: context.rule.message }];
+  }
+  return [];
+};

package/functions/apq-response-media-type.js

@@ -6,7 +6,7 @@
  * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
  */
 
-const NO_BODY_CODES = new Set(['204']);
+const BODY_ALLOWED_METHODS = new Set(['post', 'put', 'patch']);
 
 function parseExceptions(value) {
   return new Set(
@@ -29,39 +29,42 @@ module.exports = (given, options, context) => {
   const exceptions = parseExceptions(options && options['media-type-exceptions']);
 
   const root = context.document.parserResult.data;
+  const path = context.path;
+  const lastSegment = path[path.length - 1];
 
   if (root.swagger) {
-    const produces = given.produces ?? root.produces;
+    if (given.responses === undefined) return errors;
 
-    if (
-      !produces ||
-      !Array.isArray(produces) ||
-      !produces.some((mediaType) => isSupported(String(mediaType).toLowerCase(), defaultMediaType, exceptions))
-    ) {
+    const method = path[path.length - 1];
+    if (!BODY_ALLOWED_METHODS.has(method)) return errors;
+
+    const hasOwnProduces = given.produces !== undefined && given.produces !== null;
+    const produces = hasOwnProduces ? given.produces : root.produces;
+    const supported = Array.isArray(produces) && produces.some((mediaType) => isSupported(String(mediaType).toLowerCase(), defaultMediaType, exceptions));
+    if (!supported) {
       errors.push({
         message: context.rule.message,
-        path: [...context.path]
+        path: hasOwnProduces ? [...path, 'produces'] : [...path]
       });
     }
 
     return errors;
   }
 
-  const responses = given.responses;
-  if (!responses) return errors;
-
-  for (const [statusCode, response] of Object.entries(responses)) {
-    if (NO_BODY_CODES.has(statusCode)) continue;
+  if (given.responses !== undefined) return errors;
 
-    const contentTypes = response?.content ? Object.keys(response.content) : [];
+  if (lastSegment === 'content') {
+    const contentTypes = Object.keys(given);
     const supported = contentTypes.some((mediaType) => isSupported(mediaType.toLowerCase(), defaultMediaType, exceptions));
-
     if (!supported) {
-      errors.push({
-        message: context.rule.message,
-        path: [...context.path, 'responses', statusCode]
-      });
+      errors.push({ message: context.rule.message, path: [...path] });
     }
+    return errors;
+  }
+
+  const hasContentKey = given.content !== undefined && given.content !== null;
+  if (!hasContentKey) {
+    errors.push({ message: context.rule.message, path: [...path] });
   }
 
   return errors;

package/functions/apq-response-no-content.js

@@ -0,0 +1,27 @@
+/**
+ * @param {object} given - the 204 response object
+ * @param {object} options - unused
+ * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
+ */
+module.exports = (given, options, context) => {
+  if (!given || typeof given !== 'object') {
+    return [];
+  }
+
+  const doc = context.document?.data ?? {};
+  const isOAP2 = typeof doc.swagger === 'string';
+  const field = isOAP2 ? 'schema' : 'content';
+  const value = given[field];
+
+  const isEmpty = value === undefined || value === null
+    || (typeof value === 'object' && !Array.isArray(value) && Object.keys(value).length === 0);
+
+  if (isEmpty) {
+    return [];
+  }
+
+  return [{
+    message: 'OAR049: 204 No Content MUST NOT return any content.',
+    path: [...(context.path || []), field],
+  }];
+};