api-quality-spectral-ruleset 1.5.0-beta.2 → 1.5.0-beta.4

package/apq-spectral.yaml

@@ -34,6 +34,17 @@ functions:
   - apq-query-params-optional
   - apq-wso2-scopes-valid
   - apq-numeric-path-param
+  - apq-numeric-invalid-format
+  - apq-numeric-missing-format
+  - apq-numeric-well-defined-format
+  - apq-string-parameter-integrity
+  - apq-example-schema-types
+  - apq-standard-response-schema
+  - apq-allowed-http-verbs
+  - apq-url-naming-convention
+  - apq-mandatory-response-codes
+  - apq-rate-limit-response
+  - apq-forbidden-query-format
 extends:
   - spectral:asyncapi
   - spectral:oas
@@ -111,12 +122,14 @@ rules:
         function: truthy
   apiq:OAR008:
     description: "HTTP verbs not encouraged."
-    message: "OAR008: Only the REST standard verbs are allowed (POST, GET, PUT, PATCH and DELETE)."
+    message: "{{error}}"
     documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR008.md"
     severity: error
-    given: "$.paths[*][head,options,trace]"
+    given: "$.paths[*]"
     then:
-      function: falsy
+      function: apq-allowed-http-verbs
+      functionOptions:
+        allowed-verbs: "get,post,put,delete,patch"
   apiq:OAR009:
     description: "Default request media type should be defined for operations."
     message: "OAR009: Default request media type is mandatory."
@@ -132,18 +145,21 @@ rules:
     given: "$.paths[*][get,post,put,patch,delete]"
     then:
       function: apq-response-media-type
+      functionOptions:
+        default-media-type: "application/json"
+        media-type-exceptions: "-"
   apiq:OAR011:
-    description: "URLs should follow the specified naming convention: all literal path segments must be in kebab-case."
-    message: "OAR011: The resource names with more than two words must be compliant with the standard naming convention (kebab-case)."
+    description: "URLs should follow the configured naming convention (default kebab-case): all literal path segments must comply."
+    message: "{{error}}"
     documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR011.md"
     severity: error
     given:
       - "$.paths[*]~"
       - "$.servers[*].url"
     then:
-      function: pattern
+      function: apq-url-naming-convention
       functionOptions:
-        match: "^(https?:\\/\\/[^\\/]+)?(\\/(?:[a-z0-9]+(?:-[a-z0-9]+)*|\\{[^}]+\\}))*\\/?$"
+        naming-convention: "kebab-case"
   apiq:OAR012:
     description: "Path params, query params, object names and property names should follow the configured naming convention. You can configure snake_case (default), kebab-case, camelCase or UpperCamelCase"
     message: "OAR012: Path params, query params, object names and property names must follow the configured naming convention."
@@ -196,29 +212,10 @@ 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' || (@.type && @.type.indexOf && (@.type.indexOf('number') > -1 || @.type.indexOf('integer') > -1))))]"
+    resolved: false
+    given: "$..[?(@ && @.type)]"
     then:
-      function: schema
-      functionOptions:
-        schema:
-          required: [format]
-          allOf:
-            - if:
-                properties:
-                  type:
-                    const: integer
-              then:
-                properties:
-                  format:
-                    enum: [int32, int64, uint32, uint64]
-            - if:
-                properties:
-                  type:
-                    const: number
-              then:
-                properties:
-                  format:
-                    enum: [float, double, decimal]
+      function: apq-numeric-invalid-format
   apiq:OAR017:
     description: "Resource path should alternate static and parametrized parts."
     message: "OAR017: Resource path should alternate static and parametrized parts"
@@ -228,7 +225,7 @@ rules:
     then:
       function: apq-alternate-paths
       functionOptions:
-        except: ["me", "get", "search", "delete"]
+        exclude_patterns: "get,me,search,delete"
   apiq:OAR018:
     description: Operation not recommended for resource path depending on HTTP verb
     message: "OAR018: Operation not recommended for resource path: {{path}} ({{verb}})"
@@ -368,46 +365,26 @@ rules:
       field: "headers.Location.schema.type"
       function: truthy
   apiq:OAR028:
-    description: "$filter must be defined as a query parameter in all collection operations (excluding detail endpoints and health checks)."
-    message: "OAR028: $filter must be defined as a query parameter in this operation."
+    description: "$filter must be defined as a query parameter in the collection GET operations selected by the configured paths."
+    message: "{{error}}"
     severity: warn
-    given: "$.paths[?(!@property.match(/\\/me(\\/|$)/) && !@property.match(/\\/\\{[^}]+\\}$/) && !@property.match(/status|health|ping/))].get"
+    given: "$.paths"
     then:
-      function: apq-has-filter-query-param
+      function: apq-collection-query-param-required
+      functionOptions:
+        parameterName: "$filter"
+        paths: "/examples"
+        pathValidationStrategy: "/include"
   apiq:OAR029:
     description: "A response not compliant with the standard may cause application issues."
-    message: "OAR029: A response not compliant with the standard may cause application issues."
+    message: "{{error}}"
     severity: error
-    given: "$.components.schemas.errorResponse"
+    given: "$.paths"
     then:
-      function: schema
+      function: apq-standard-response-schema
       functionOptions:
-        schema:
-          type: object
-          properties:
-            properties:
-              type: object
-              properties:
-                error:
-                  type: object
-                  properties:
-                    properties:
-                      type: object
-                      properties:
-                        code:
-                          type: string
-                        message:
-                          type: string
-                        details:
-                          type: array
-                        httpStatus:
-                          type: integer
-                      required:
-                        - code
-                        - message
-                        - httpStatus
-          required:
-            - properties
+        response-schema: '{"type":"object","properties":{"status":{"type":"object","properties":{"code":{"type":"integer"},"description":{"type":"string"},"internal_code":{"type":"string"},"errors":{"type":"array","nullable":true,"items":{"type":"object","properties":{"name":{"type":"string"},"value":{"type":"string"}}}}},"required":["code"]},"payload":{"type":"any"}},"required":["status","payload"]}'
+        path-exclusions: "/status"
   apiq:OAR030:
     description: "The configured status endpoint must be declared with the configured HTTP method."
     message: "OAR030: The required status endpoint is not declared or does not have the required method."
@@ -435,13 +412,13 @@ rules:
         validateProperty: true
   apiq:OAR032:
     description: "Ambiguous path parts not encouraged."
-    message: "OAR032: When reading a URL, it must be possible to interpret which resources it is referring to in a concrete way. Ambiguous names in resources must be avoided."
+    message: "{{error}}"
     severity: error
     given: "$.paths.*~"
     then:
       function: apq-check-ambiguous-path
       functionOptions:
-        ambiguous-words: "elements,instances,resources,values,terms,objects,items"
+        ambiguous-names: "elementos,instancias,recursos,valores,terminos,objetos,articulos,elements,instances,resources,values,terms,objects,items"
   apiq:OAR033:
     description: "Request operation parameters must not include forbidden headers (Accept, Content-Type, Authorization). Note: This validates REQUEST headers, not response headers (see OAR053/114 for response header validation)."
     message: "OAR033: The request header parameter '{{value}}' is not allowed in operations."
@@ -688,10 +665,10 @@ 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' || (@.type && @.type.indexOf && (@.type.indexOf('integer') > -1 || @.type.indexOf('number') > -1))))]"
+    resolved: false
+    given: "$..[?(@ && @.type)]"
     then:
-      field: format
-      function: truthy
+      function: apq-numeric-missing-format
   apiq:OAR053:
     description: "Response headers for API observability and tracing must be defined (excluding 204 responses and health endpoints)."
     message: "OAR053: Response must include mandatory headers and exclude forbidden headers."
@@ -732,75 +709,59 @@ rules:
         path-exclusions: "/status"
   apiq:OAR061:
     description: "Ensure get have mandatory response codes"
-    message: "OAR061: Ensure get have the mandatory response codes"
+    message: "{{error}}"
     severity: error
-    given: "$.paths[?(@property !== '/status')].get.responses"
+    given: "$.paths[*][get]"
     then:
-      function: schema
+      function: apq-mandatory-response-codes
       functionOptions:
-        schema:
-          oneOf:
-          - required: ['200']
-          - required: ['202']
-          - required: ['206']
-            not:
-              required: ['201', '204']
+        mandatory-response-codes: "200, 202, 206"
+        paths: "/status, /another"
+        pathValidationStrategy: "/exclude"
   apiq:OAR062:
     description: "Ensure post have mandatory response codes"
-    message: "OAR062: Ensure post have the mandatory response codes"
+    message: "{{error}}"
     severity: error
-    given: "$.paths[?(@property !== '/status')].post.responses"
+    given: "$.paths[*][post]"
     then:
-      function: schema
+      function: apq-mandatory-response-codes
       functionOptions:
-        schema:
-          oneOf:
-          - required: ['200']
-          - required: ['201']
-          - required: ['202']
-          - required: ['204']
-          - required: ['206']
+        mandatory-response-codes: "200, 201, 202, 204, 206"
+        paths: "/status, /another"
+        pathValidationStrategy: "/exclude"
   apiq:OAR063:
     description: "Ensure put have mandatory response codes"
-    message: "OAR063: Ensure put have the mandatory response codes"
+    message: "{{error}}"
     severity: error
-    given: "$.paths[?(@property !== '/status')].put.responses"
+    given: "$.paths[*][put]"
     then:
-      function: schema
+      function: apq-mandatory-response-codes
       functionOptions:
-        schema:
-          oneOf:
-          - required: ['200']
-          - required: ['202']
-          - required: ['204']
-          - required: ['206']
+        mandatory-response-codes: "200, 202, 204, 206"
+        paths: "/status, /another"
+        pathValidationStrategy: "/exclude"
   apiq:OAR064:
     description: "Ensure patch have mandatory response codes"
-    message: "OAR064: Ensure patch have the mandatory response codes"
+    message: "{{error}}"
     severity: error
-    given: "$.paths[?(@property !== '/status')].patch.responses"
+    given: "$.paths[*][patch]"
     then:
-      function: schema
+      function: apq-mandatory-response-codes
       functionOptions:
-        schema:
-          oneOf:
-          - required: ['200']
-          - required: ['202']
-          - required: ['204']
-          - required: ['206']
+        mandatory-response-codes: "200, 202, 204, 206"
+        paths: "/status, /another"
+        pathValidationStrategy: "/exclude"
   apiq:OAR065:
     description: "Ensure delete have mandatory response codes"
-    message: "OAR065: Ensure delete have the mandatory response codes"
+    message: "{{error}}"
     severity: error
-    given: "$.paths[?(@property !== '/status')].delete.responses"
+    given: "$.paths[*][delete]"
     then:
-      function: schema
+      function: apq-mandatory-response-codes
       functionOptions:
-        schema:
-          oneOf:
-          - required: ['200']
-          - required: ['202']
-          - required: ['204']
+        mandatory-response-codes: "200, 202, 204"
+        paths: "/status, /another"
+        pathValidationStrategy: "/exclude"
   apiq:OAR066:
     description: "RequestBody and Responses schema property names must be compliant with the snake_case naming convention."
     message: "OAR066: RequestBody and Responses schema property names must be compliant with the snake_case naming convention."
@@ -871,10 +832,12 @@ rules:
     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 !== '/status' && @property !== '/health' && @property !== '/health-check' && @property !== '/ping' && @property !== '/liveness' && @property !== '/readiness')][*].responses"
+    given: "$.paths[*][get,post,put,patch,delete]"
     then:
-      field: "429"
-      function: truthy
+      function: apq-rate-limit-response
+      functionOptions:
+        paths: "/status, /health, /health-check, /ping, /liveness, /readiness"
+        pathValidationStrategy: "/exclude"
   apiq:OAR074:
     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."
@@ -889,47 +852,25 @@ rules:
     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' || (@.schema.type && @.schema.type.indexOf && @.schema.type.indexOf('string') > -1)) && @.in == 'path')]"
+    resolved: false
+    given:
+      - "$.paths[*][*].parameters[*]"
+      - "$.paths[*].parameters[*]"
+      - "$.components.parameters[*]"
+      - "$.parameters[*]"
     then:
-      function: schema
+      function: apq-string-parameter-integrity
       functionOptions:
-        schema:
-          type: object
-          properties:
-            schema:
-              anyOf:
-                - required: ["minLength"]
-                - required: ["maxLength"]
-                - required: ["pattern"]
-                - required: ["enum"]
+        parameter_integrity: "minLength,maxLength,pattern,enum"
   apiq:OAR076:
     description: "Schema should use well-defined type and format."
     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' || (@.type && @.type.indexOf && (@.type.indexOf('number') > -1 || @.type.indexOf('integer') > -1))))]"
+    resolved: false
+    given: "$..[?(@ && @.type)]"
     then:
-      function: schema
-      functionOptions:
-        schema:
-          required: [format]
-          allOf:
-            - if:
-                properties:
-                  type:
-                    const: integer
-              then:
-                properties:
-                  format:
-                    enum: [int32, int64]
-            - if:
-                properties:
-                  type:
-                    const: number
-              then:
-                properties:
-                  format:
-                    enum: [float, double]
+      function: apq-numeric-well-defined-format
   apiq:OAR077:
     description: "All parameters in query must be snake_case."
     message: "OAR077: All parameters in query must be snake_case."
@@ -957,7 +898,8 @@ rules:
     then:
       function: apq-require-response-on-path-params
       functionOptions:
-        response: "404"
+        paths: "/status"
+        pathValidationStrategy: "/exclude"
   apiq:OAR080:
     description: "The security scheme must be among those allowed by the organization and must be complete."
     message: "OAR080: The security scheme '{{property}}' must be among those allowed by the organization and must be complete."
@@ -995,15 +937,16 @@ rules:
       functionOptions:
         notMatch: "^(email|password)$"
   apiq:OAR084:
-    description: "The format password should not pass through the querystring."
-    message: "OAR084: The format password should not be used in querystring parameters."
+    description: "Some formats should not pass through this querystring."
+    message: "{{error}}"
     severity: error
     given: "$.paths[*][get,post,put,patch,delete].parameters[?(@.in == 'query')]"
     then:
-      field: "schema.format"
-      function: pattern
+      function: apq-forbidden-query-format
       functionOptions:
-        notMatch: "^password$"
+        forbidden-query-formats: "password"
+        paths: "/examples"
+        pathValidationStrategy: "/include"
   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.0.4, 3.1.0, 3.1.1, 3.1.2, 3.2.0."
     message: "{{error}}"
@@ -1199,19 +1142,10 @@ rules:
     description: "The schemas should match the provided examples."
     message: "OAR108: Schema does not match the provided example."
     severity: "error"
-    given: 
-      - "$.paths['/item'].get.responses['200'].content['application/json'].example"
-      - "$.paths['/item'].get.responses['200'].examples['application/json']"
+    resolved: false
+    given: "$.paths[*][*].responses[*]"
     then:
-      - function: "schema"
-        functionOptions:
-          schema:
-            type: "object"
-            properties:
-              id:
-                type: "integer"
-              nombre:
-                type: "string" 
+      function: apq-example-schema-types
   apiq:OAR109:
     description: "Use default response instead of directly specifying 5XX codes."
     message: "OAR109: Use default response instead of specifying 5XX codes directly."
@@ -1265,9 +1199,8 @@ rules:
     message: "OAR115: All fields in the required array must be defined in schema properties."
     documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR115.md"
     severity: warn
-    given:
-      - "$.components.schemas[*]"
-      - "$.definitions[*]"
+    resolved: false
+    given: "$..[?(@ && @.required)]"
     then:
       function: apq-required-fields-exist
   apiq:OAR116:

package/functions/apq-allowed-http-verbs.js

@@ -0,0 +1,31 @@
+const HTTP_VERBS = ['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace'];
+
+/**
+ * @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 allowedVerbs = ((options && options['allowed-verbs']) || '')
+    .split(',')
+    .map((verb) => verb.trim().toLowerCase())
+    .filter(Boolean);
+
+  const basePath = context.path || [];
+  const errors = [];
+
+  HTTP_VERBS.forEach((verb) => {
+    if (Object.prototype.hasOwnProperty.call(given, verb) && !allowedVerbs.includes(verb)) {
+      errors.push({
+        message: `HTTP verb '${verb}' is not encouraged. Only the following verbs are allowed: ${allowedVerbs.join(', ')}.`,
+        path: [...basePath, verb]
+      });
+    }
+  });
+
+  return errors;
+};

package/functions/apq-alternate-paths.js

@@ -1,18 +1,22 @@
-
 const isVariable = (part) => {
   return (part.startsWith('{') && part.endsWith('}'));
 }
 
-module.exports = (given, { except }, context) => {
+module.exports = (given, options, context) => {
   const result = [];
   const paths = given || [];
   if (paths.length === 0) return result;
 
+  const excludePatterns = ((options && options['exclude_patterns']) || '')
+    .split(',')
+    .map((pattern) => pattern.trim())
+    .filter(Boolean);
+
   const parts = paths.substr(1).split('/').filter(p => p.length > 0);
   if (parts.length === 0) return result;
   const firstPart = parts.shift();
   let previousIsVar;
-  if (except && except.includes(firstPart)) {
+  if (excludePatterns.includes(firstPart)) {
     previousIsVar = true;
   } else if (isVariable(firstPart)) {
     return [{ message: context.rule.message }];
@@ -21,7 +25,7 @@ module.exports = (given, { except }, context) => {
   }
 
   for (const part of parts) {
-    if (except && except.includes(part)) {
+    if (excludePatterns.includes(part)) {
       previousIsVar = true;
       continue;
     }

package/functions/apq-check-ambiguous-path.js

@@ -1,52 +1,38 @@
+const PARAM_REGEX = /\{[^}{]*}/g;
+
+const DEFAULT_AMBIGUOUS_NAMES =
+  'elementos,instancias,recursos,valores,terminos,objetos,articulos,elements,instances,resources,values,terms,objects,items';
+
 /**
- * Validates that URL path segments use clear, unambiguous names
  * @param {string} given - The path key (e.g. "/users/{id}/items")
- * @param {object} options - Function options
- * @param {string} options.ambiguous-words - Comma-separated list of ambiguous words
+ * @param {object} options
+ * @param {string} options['ambiguous-names']
  * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
  */
 module.exports = (given, options, context) => {
-  const results = [];
-
   if (typeof given !== 'string') {
-    return results;
+    return [];
   }
 
-  // Default ambiguous words (from the original regex)
-  const defaultAmbiguousWords = [
-    'elements', 'instances', 'resources', 'values', 'terms', 'objects', 'items'
-  ];
-
-  // Parse custom ambiguous words from options if provided
-  let ambiguousWords = defaultAmbiguousWords;
-  if (options && options['ambiguous-words']) {
-    ambiguousWords = options['ambiguous-words']
+  const forbiddenValues = new Set(
+    ((options && options['ambiguous-names']) || DEFAULT_AMBIGUOUS_NAMES)
       .split(',')
-      .map(w => w.trim().toLowerCase())
-      .filter(Boolean);
-  }
+      .map((value) => value.trim())
+      .filter(Boolean)
+  );
 
-  // Split path into segments and filter out parameters
-  const segments = given
-    .split('/')
-    .filter(segment => {
-      // Keep only static segments (not empty, not {param})
-      return segment.length > 0 && !segment.startsWith('{');
-    });
+  const pathWithoutParams = given.replace(PARAM_REGEX, '');
+  const pathParts = pathWithoutParams.split('/').filter(Boolean);
+  const forbidden = pathParts.filter((part) => forbiddenValues.has(part));
 
-  // Check each segment for ambiguous words
-  for (const segment of segments) {
-    const lowerSegment = segment.toLowerCase();
-    for (const word of ambiguousWords) {
-      if (lowerSegment.includes(word)) {
-        results.push({
-          message: `${context.rule.message || 'OAR032'}: Path segment '${segment}' is ambiguous. Avoid using words like '${word}' in resource names.`,
-          path: context.path
-        });
-        break; // Report only once per segment
-      }
-    }
+  if (forbidden.length === 0) {
+    return [];
   }
 
-  return results;
+  return [
+    {
+      message: `Ambiguous name(s) found in path: ${forbidden.join(', ')}.`,
+      path: context.path
+    }
+  ];
 };