api-quality-spectral-ruleset 1.6.0 → 1.7.0

package/README.md

@@ -1,6 +1,6 @@
 <!-- README.md -->
 
-[![Node.js CI](https://github.com/apiaddicts/apquality-spectral/actions/workflows/node.js.yml/badge.svg)](https://github.com/apiaddicts/apquality-spectral/actions/workflows/node.js.yml) ![Coverage](./coverage/badges.svg)
+[![Node.js CI](https://github.com/apiaddicts/apiaddicts-style-guide-spectral/actions/workflows/node.js.yml/badge.svg)](https://github.com/apiaddicts/apiaddicts-style-guide-spectral/actions/workflows/node.js.yml) ![Coverage](./coverage/badges.svg)
 
 # APIAddicts Style Guide Spectral
 
@@ -26,19 +26,19 @@ The Spectral Ruleset requires Node version 14 or later.
 
 You can specify the ruleset directly on the command line:
 
-`spectral lint -r https://raw.githubusercontent.com/apiaddicts/apquality-spectral/refs/heads/main/apq-spectral.yaml <api definition file>`
+`spectral lint -r https://raw.githubusercontent.com/apiaddicts/apiaddicts-style-guide-spectral/refs/heads/main/apq-spectral.yaml <api definition file>`
 
 Or you can create a Spectral configuration file (`.spectral.yaml`) that references the ruleset:
 
 ```yaml
 extends:
-  - https://raw.githubusercontent.com/apiaddicts/apquality-spectral/refs/heads/main/apq-spectral.yaml
+  - https://raw.githubusercontent.com/apiaddicts/apiaddicts-style-guide-spectral/refs/heads/main/apq-spectral.yaml
 ```
 
 ### Example
 
 ```bash
-spectral lint -r https://raw.githubusercontent.com/apiaddicts/apquality-spectral/refs/heads/main/apq-spectral.yaml petstore.yaml
+spectral lint -r https://raw.githubusercontent.com/apiaddicts/apiaddicts-style-guide-spectral/refs/heads/main/apq-spectral.yaml petstore.yaml
 ```
 
 ### Using the Spectral VSCode extension

package/apq-spectral.yaml

@@ -58,7 +58,7 @@ rules:
   apiq:OAR001:
     description: "For security reasons and as a REST best practice, the HTTPS protocol is mandatory."
     message: "OAR001: HTTPS protocol is mandatory."
-    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR001.md"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR001.md"
     severity: "error"
     given: "$.servers[*].url"
     then:
@@ -68,7 +68,7 @@ rules:
   apiq:OAR002:
     description: "A wrong scope definition may cause problems to import the API definition into WSO2."
     message: "{{error}}"
-    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR002.md"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR002.md"
     severity: "error"
     given: "$.x-wso2-security.apim.x-wso2-scopes"
     then:
@@ -76,7 +76,7 @@ rules:
   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."
-    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR003.md"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR003.md"
     severity: "error"
     given: "$.x-wso2-security.apim.x-wso2-scopes[*]"
     then:
@@ -86,7 +86,7 @@ rules:
   apiq:OAR004:
     description: "A role with forbidden characters may cause problems in some applications."
     message: "{{error}}"
-    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR004.md"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR004.md"
     severity: "error"
     given: "$.x-wso2-security.apim.x-wso2-scopes[*].roles"
     then:
@@ -96,7 +96,7 @@ rules:
   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: "{{error}}"
-    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR005.md"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR005.md"
     severity: "error"
     resolved: false
     given: "$"
@@ -106,7 +106,7 @@ rules:
     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."
     severity: "error"
-    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR006.md"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR006.md"
     given: "$.paths[*][post,put,patch]"
     then:
       - field: "requestBody"
@@ -116,7 +116,7 @@ rules:
   apiq:OAR007:
     description: "Routes must define response media types supported by the API"
     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"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR007.md"
     severity: "error"
     given:
       - "$.paths[*][post,put,patch]"
@@ -128,7 +128,7 @@ rules:
   apiq:OAR008:
     description: "HTTP verbs not encouraged."
     message: "{{error}}"
-    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR008.md"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR008.md"
     severity: error
     given: "$.paths[*]"
     then:
@@ -162,7 +162,7 @@ rules:
   apiq:OAR011:
     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"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR011.md"
     severity: error
     given:
       - "$.paths[*]~"
@@ -174,7 +174,7 @@ rules:
   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."
-    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR012.md"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR012.md"
     severity: warn
     given:
       - "$.paths[*][*].parameters[?(@.in == 'path' || @.in == 'query')].name"
@@ -197,7 +197,7 @@ rules:
   apiq:OAR014:
     description: "Resources depth level should be below the non-suggested range."
     message: "{{error}}"
-    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR014.md"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR014.md"
     severity: warn
     given: "$.paths.*~"
     then:
@@ -221,7 +221,7 @@ rules:
   apiq:OAR016:
     description: "Numeric types requires a valid format."
     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"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR016.md"
     severity: error
     resolved: false
     given: "$..[?(@ && @.type)]"
@@ -230,7 +230,7 @@ rules:
   apiq:OAR017:
     description: "Resource path should alternate static and parametrized parts."
     message: "OAR017: Resource path should alternate static and parametrized parts"
-    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR017.md"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR017.md"
     severity: error
     given: "$.paths.*~"
     then:
@@ -240,7 +240,7 @@ rules:
   apiq:OAR018:
     description: Operation not recommended for resource path depending on HTTP verb
     message: "OAR018: Operation not recommended for resource path: {{path}} ({{verb}})"
-    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR018.md"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR018.md"
     severity: warn
     given: "$.paths"
     then:
@@ -322,7 +322,7 @@ rules:
   apiq:OAR022:
     description: "$orderby must be defined as a query parameter in the collection GET operations selected by the configured paths."
     message: "{{error}}"
-    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR022.md"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR022.md"
     severity: warn
     given: "$.paths"
     then:
@@ -350,7 +350,7 @@ rules:
   apiq:OAR025:
     description: "$limit must be defined as an integer query parameter in the collection GET operations selected by the configured paths."
     message: "{{error}}"
-    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR025.md"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR025.md"
     severity: error
     given: "$.paths"
     then:
@@ -439,14 +439,16 @@ rules:
       functionOptions:
         notMatch: "^(Accept|Content-Type|Authorization)$"
   apiq:OAR034:
-    description: "A paged response must comply with the standard paging schema (start, limit, links with self/previous/next, numPages, total)."
-    message: "OAR034: Paged response schema does not match the required standard."
+    description: "GET success JSON responses on collection paths must define an object schema with a paging block that complies with paging-schema (required start, limit and links with self/previous/next; optional numPages and total as integers)."
+    message: "{{error}}"
     severity: error
-    given: "$.paths[*][get].responses[?(@property != '204' && @property != '304' && @property != 'default')]..schema"
+    given: "$.paths[*].get.responses[*]"
     then:
       function: apq-paged-response-check
       functionOptions:
         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"}'
+        paths: "/status,/health,/ping,**/me"
+        pathValidationStrategy: "/exclude"
   apiq:OAR035:
     description: "Response code 401 must be defined for operations with security schemes defined."
     message: "{{error}}"
@@ -477,7 +479,7 @@ rules:
     then:
       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."
+    description: "The 201 response schema of a POST operation must only have the allowed top-level properties ('data' or 'error' by default), each with at least one sub-property, and every required one."
     message: "{{error}}"
     severity: error
     given: "$.paths.*.post.responses['201']"
@@ -485,10 +487,14 @@ rules:
       function: apq-valid-response-schema
       functionOptions:
         data-property: data
+        allowed-properties: ""
+        required-properties: ""
+        paths: "/me,/health,/ping,/status"
+        pathValidationStrategy: "/exclude"
   apiq:OAR039:
     description: "Response codes must be defined according to the standard depending on the HTTP verb and resource path."
     message: "{{error}}"
-    documentationUrl: https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR039.md
+    documentationUrl: https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR039.md
     severity: error
     given: "$.paths[*][*]"
     then:
@@ -533,7 +539,7 @@ rules:
   apiq:OAR041:
     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"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR041.md"
     severity: "error"
     resolved: false
     given: "$"
@@ -553,7 +559,7 @@ 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"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR043.md"
     severity: error
     given:
       - $.paths.*.*.parameters.*.in
@@ -602,7 +608,7 @@ rules:
     - "$.paths[*].patch"
     - "$.paths[*].delete"
     then:
-      function: schema              
+      function: schema
       functionOptions:
         schema:
           type: object
@@ -621,7 +627,7 @@ rules:
   apiq:OAR048:
     description: APIs must define at most one body parameter.
     message: "OAR048: An operation can have at most one body parameter"
-    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR048.md"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR048.md"
     severity: error
     given: "$.paths[*][*]"
     then:
@@ -657,7 +663,7 @@ rules:
   apiq:OAR052:
     description: "Numeric schema types must define a format."
     message: "OAR052: Numeric types requires a format"
-    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR052.md"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR052.md"
     severity: warn
     resolved: false
     given: "$..[?(@ && @.type)]"
@@ -666,7 +672,7 @@ rules:
   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."
-    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR053.md"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR053.md"
     severity: error
     given: "$.paths[*][*].responses[*]"
     then:
@@ -863,7 +869,7 @@ rules:
   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"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR076.md"
     severity: error
     resolved: false
     given: "$..[?(@ && @.type)]"
@@ -884,7 +890,7 @@ rules:
   apiq:OAR078:
     description: "All API methods must have security defined."
     message: "OAR078: Operation must have security defined."
-    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR078.md"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR078.md"
     severity: error
     given: "$"
     then:
@@ -892,7 +898,7 @@ rules:
   apiq:OAR079:
     description: "Operations with path parameters should include a 404 Not Found response."
     message: "OAR079: Path parameter present, but missing 404 Not Found response."
-    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR079.md"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR079.md"
     severity: "warn"
     given: "$.paths[*][get,post,put,patch,delete]"
     then:
@@ -1010,7 +1016,7 @@ rules:
   apiq:OAR091:
     description: "Parameters must contain only $ref references."
     message: "OAR091: Parameters must contain only $ref references."
-    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR091.md"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR091.md"
     severity: error
     resolved: false
     given: "$.paths[*][get,post,put,patch,delete].parameters[*]"
@@ -1176,7 +1182,7 @@ rules:
   apiq:OAR113:
     description: "Field or extension must be at the assigned location"
     message: "OAR113: Field or extension x-custom-example must be at the assigned location"
-    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR113.md"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR113.md"
     severity: warn
     given: "$"
     then:
@@ -1187,7 +1193,7 @@ rules:
   apiq:OAR114:
     description: "Response headers for API security and key management must be defined (excluding 204 responses)."
     message: "OAR114: Response must include mandatory headers and exclude forbidden headers."
-    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR114.md"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR114.md"
     severity: "error"
     given: "$.paths[*][*].responses[*]"
     then:
@@ -1200,7 +1206,7 @@ rules:
   apiq:OAR115:
     description: "All fields listed in the required array must be defined in the schema properties."
     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"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR115.md"
     severity: warn
     resolved: false
     given: "$..[?(@ && @.required)]"
@@ -1209,7 +1215,7 @@ rules:
   apiq:OAR116:
     description: "Every API path must match the configured regular expression."
     message: "{{error}}"
-    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR116.md"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR116.md"
     severity: error
     given: "$.paths.*~"
     then:
@@ -1219,10 +1225,10 @@ rules:
   apiq:OAR117:
     description: "The API title must not match the configured forbidden regular expression."
     message: "{{error}}"
-    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR117.md"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR117.md"
     severity: error
     given: "$.info.title"
     then:
       function: apq-forbidden-title-pattern
       functionOptions:
-        forbidden-pattern: "(?!)"
+        forbidden-pattern: "(?!)"

package/functions/apq-paged-response-check.js

@@ -1,124 +1,319 @@
-module.exports = (schema, options = {}, context) => {
-  const results = [];
+const DEFAULT_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',
+};
 
-  if (!schema || typeof schema !== 'object') {
-    return results;
-  }
+const DEFAULT_PAGING_PROPERTY = 'paging';
+const DEFAULT_PATHS = '/status,/health,/ping,**/me';
+
+const SUCCESS_CODE_REGEX = /^2(\d\d|XX)$/i;
+const NO_CONTENT_CODE = '204';
+const MEDIA_TYPE_TOKEN = /^[a-z0-9!#$&^_.+-]+$/;
 
-  // Parse paging schema from options
-  let pagingSchema = {};
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+const parsePagingSchema = (raw) => {
+  if (isObject(raw)) return raw;
+  if (typeof raw !== 'string' || raw.trim() === '') return DEFAULT_PAGING_SCHEMA;
   try {
-    const pagingSchemaStr = options['paging-schema'] || defaultPagingSchema;
-    pagingSchema = typeof pagingSchemaStr === 'string'
-      ? JSON.parse(pagingSchemaStr)
-      : pagingSchemaStr;
+    const parsed = JSON.parse(raw);
+    return isObject(parsed) ? parsed : DEFAULT_PAGING_SCHEMA;
   } catch (err) {
-    return [{
-      message: `${context.rule.name.split(':').pop()}: Invalid paging-schema configuration: ${err.message}`,
-      path: context.path,
-    }];
+    return DEFAULT_PAGING_SCHEMA;
   }
+};
 
-  const pagingPropertyName = pagingSchema.pagingPropertyName || 'paging';
-  const requiredFields = pagingSchema.required || [];
-  const properties = pagingSchema.properties || {};
+const declaredTypes = (schema) => {
+  if (!isObject(schema)) return [];
+  if (typeof schema.type === 'string') return [schema.type];
+  if (Array.isArray(schema.type)) return schema.type.filter((t) => typeof t === 'string');
+  return [];
+};
 
-  // Check if schema doesn't have properties at all - skip validation
-  if (!schema.properties) {
-    return results;
+const isNullSchema = (schema) => {
+  const types = declaredTypes(schema);
+  return types.length > 0 && types.every((t) => t === 'null');
+};
+
+const unwrapNullable = (schema, schemaPath) => {
+  let current = schema;
+  let currentPath = schemaPath;
+  const seen = new Set();
+  while (isObject(current) && !seen.has(current)) {
+    seen.add(current);
+    const key = ['oneOf', 'anyOf'].find((k) => Array.isArray(current[k]));
+    if (!key || current.properties || current.items || current.allOf) break;
+    const branches = current[key].map((branch, index) => ({ branch, index })).filter(({ branch }) => !isNullSchema(branch));
+    if (branches.length !== 1) break;
+    currentPath = [...currentPath, key, branches[0].index];
+    current = branches[0].branch;
   }
+  return { schema: current, path: currentPath };
+};
+
+const buildView = (schema, schemaPath) => {
+  const root = unwrapNullable(schema, schemaPath);
+  const view = {
+    types: new Set(),
+    properties: new Map(),
+    required: new Set(),
+    items: null,
+    path: root.path,
+    rootSchema: root.schema,
+    propertiesPath: null,
+    requiredPath: null,
+  };
+  const visited = new Set();
 
-  // Check if schema has the paging property
-  if (!schema.properties[pagingPropertyName]) {
-    // Only flag if schema looks like it should have paging (has data/items/results arrays)
-    const hasArrayProperty = Object.values(schema.properties || {}).some(
-      prop => prop && prop.type === 'array'
-    );
-
-    if (hasArrayProperty) {
-      results.push({
-        message: `${context.rule.name.split(':').pop()}: Response must include '${pagingPropertyName}' property for pagination`,
-        path: context.path,
+  const collect = (node, nodePath) => {
+    const unwrapped = unwrapNullable(node, nodePath);
+    const current = unwrapped.schema;
+    const currentPath = unwrapped.path;
+    if (!isObject(current) || visited.has(current)) return;
+    visited.add(current);
+
+    declaredTypes(current).filter((t) => t !== 'null').forEach((t) => view.types.add(t));
+
+    if (isObject(current.properties)) {
+      if (!view.propertiesPath) view.propertiesPath = [...currentPath, 'properties'];
+      Object.entries(current.properties).forEach(([name, propertySchema]) => {
+        if (!view.properties.has(name)) {
+          view.properties.set(name, { schema: propertySchema, path: [...currentPath, 'properties', name] });
+        }
       });
     }
-    return results;
-  }
 
-  const pagingObj = schema.properties[pagingPropertyName];
+    if (Array.isArray(current.required)) {
+      if (!view.requiredPath) view.requiredPath = [...currentPath, 'required'];
+      current.required.filter((name) => typeof name === 'string').forEach((name) => view.required.add(name));
+    }
 
-  // Validate paging object structure
-  if (!pagingObj.properties) {
-    results.push({
-      message: `${context.rule.name.split(':').pop()}: '${pagingPropertyName}' must be an object with required properties`,
-      path: [...context.path, 'properties', pagingPropertyName],
-    });
-    return results;
+    if (isObject(current.items) && !view.items) {
+      view.items = { schema: current.items, path: [...currentPath, 'items'] };
+    }
+
+    if (Array.isArray(current.allOf)) {
+      current.allOf.forEach((member, index) => collect(member, [...currentPath, 'allOf', index]));
+    }
+  };
+
+  collect(root.schema, root.path);
+
+  if (view.types.size === 0) {
+    if (view.properties.size > 0) view.types.add('object');
+    else if (view.items) view.types.add('array');
   }
+  return view;
+};
+
+const expectedType = (template) => {
+  const types = declaredTypes(template).filter((t) => t !== 'null' && t !== 'any');
+  if (types.length > 0) return types[0];
+  if (isObject(template.properties) || Array.isArray(template.required)) return 'object';
+  if (isObject(template.items)) return 'array';
+  return null;
+};
+
+const typeMatches = (expected, actualTypes) => {
+  if (!expected || actualTypes.size === 0) return true;
+  if (actualTypes.has(expected)) return true;
+  return expected === 'number' && actualTypes.has('integer');
+};
 
-  // Check required fields
-  const missingFields = [];
-  for (const requiredField of requiredFields) {
-    if (!pagingObj.properties[requiredField]) {
-      missingFields.push(requiredField);
+const isArrayView = (view) => view.types.has('array');
+
+const typePath = (view) => (isObject(view.rootSchema) && view.rootSchema.type !== undefined ? [...view.path, 'type'] : view.path);
+
+const validateAgainstTemplate = (template, view, label, report) => {
+  if (!isObject(template)) return;
+  const type = expectedType(template);
+
+  if (type === 'array') {
+    if (isObject(template.items) && view.items) {
+      validateAgainstTemplate(template.items, buildView(view.items.schema, view.items.path), `${label}[]`, report);
     }
+    return;
   }
+  if (type !== 'object') return;
 
-  if (missingFields.length > 0) {
-    results.push({
-      message: `${context.rule.name.split(':').pop()}: Paging object must include required fields: ${missingFields.join(', ')}`,
-      path: [...context.path, 'properties', pagingPropertyName, 'properties'],
-    });
+  const requiredNames = Array.isArray(template.required) ? template.required.filter((name) => typeof name === 'string') : [];
+  const missing = requiredNames.filter((name) => !view.properties.has(name));
+  const notMarked = requiredNames.filter((name) => view.properties.has(name) && !view.required.has(name));
+
+  if (missing.length > 0) {
+    report(`'${label}' must include required properties: ${missing.join(', ')}`, view.propertiesPath || view.path);
+  }
+  if (notMarked.length > 0) {
+    report(`'${label}' must list as required: ${notMarked.join(', ')}`, view.requiredPath || view.path);
   }
 
-  // Special validation for links object if it's required
-  if (requiredFields.includes('links') && pagingObj.properties.links) {
-    const linksObj = pagingObj.properties.links;
-    if (linksObj.properties) {
-      const requiredLinks = ['self', 'previous', 'next']; // From default schema
-      const linksRequired = linksObj.required || [];
-
-      for (const requiredLink of requiredLinks) {
-        if (!linksObj.properties[requiredLink]) {
-          results.push({
-            message: `${context.rule.name.split(':').pop()}: Links object must include '${requiredLink}' property`,
-            path: [...context.path, 'properties', pagingPropertyName, 'properties', 'links', 'properties'],
-          });
-        }
-      }
+  if (!isObject(template.properties)) return;
+  Object.entries(template.properties).forEach(([name, childTemplate]) => {
+    const property = view.properties.get(name);
+    if (!property || !isObject(childTemplate)) return;
+    const childView = buildView(property.schema, property.path);
+    const childType = expectedType(childTemplate);
+    if (!typeMatches(childType, childView.types)) {
+      report(`'${label}.${name}' must be of type ${childType}`, typePath(childView));
+      return;
+    }
+    validateAgainstTemplate(childTemplate, childView, `${label}.${name}`, report);
+  });
+};
+
+const isJsonMediaType = (mediaType) => {
+  const essence = String(mediaType).split(';')[0].trim().toLowerCase();
+  const parts = essence.split('/');
+  if (parts.length !== 2 || parts[0] === '*') return true;
+  const [type, subtype] = parts;
+  if (!MEDIA_TYPE_TOKEN.test(type) || (subtype !== '*' && !MEDIA_TYPE_TOKEN.test(subtype))) return true;
+  if (type === 'application' && (subtype === 'json' || subtype === '*')) return true;
+  return subtype.endsWith('+json');
+};
+
+const pathPatterns = (raw) => {
+  let items = [];
+  if (raw === undefined) items = DEFAULT_PATHS.split(',');
+  else if (typeof raw === 'string') items = raw.split(',');
+  else if (Array.isArray(raw)) items = raw;
+  return items
+    .filter((item) => typeof item === 'string')
+    .map((item) => item.trim())
+    .filter(Boolean)
+    .map((pattern) => pattern.split('/'));
+};
+
+const isIncludeStrategy = (value) => typeof value === 'string' && value.trim().replace(/^\//, '').toLowerCase() === 'include';
 
-      // Check if links has required array
-      if (!linksRequired.includes('self') || !linksRequired.includes('previous') || !linksRequired.includes('next')) {
-        results.push({
-          message: `${context.rule.name.split(':').pop()}: Links object must require 'self', 'previous', and 'next'`,
-          path: [...context.path, 'properties', pagingPropertyName, 'properties', 'links'],
-        });
+const matchesPattern = (pattern, segments) => {
+  const match = (patternIndex, segmentIndex) => {
+    if (patternIndex === pattern.length) return segmentIndex === segments.length;
+    if (pattern[patternIndex] === '**') {
+      for (let next = segmentIndex; next <= segments.length; next += 1) {
+        if (match(patternIndex + 1, next)) return true;
       }
+      return false;
     }
+    if (segmentIndex === segments.length) return false;
+    return (pattern[patternIndex] === '*' || pattern[patternIndex] === segments[segmentIndex]) && match(patternIndex + 1, segmentIndex + 1);
+  };
+  return match(0, 0);
+};
+
+const isDetailPath = (pathKey) => pathKey.slice(pathKey.lastIndexOf('/') + 1).startsWith('{');
+
+const isUnresolvedRef = (value) => isObject(value) && typeof value.$ref === 'string';
+
+const producedMediaTypes = (document, pathKey) => {
+  const pathItem = isObject(document) && isObject(document.paths) ? document.paths[pathKey] : null;
+  const operation = isObject(pathItem) ? pathItem.get : null;
+  const listed = (value) => (Array.isArray(value) && value.length > 0 ? value : null);
+  return listed(isObject(operation) ? operation.produces : null) || listed(isObject(document) ? document.produces : null);
+};
+
+const evaluatedSchemas = (response, responsePath, document, pathKey, isOas2) => {
+  const schemas = [];
+  const missing = [];
+  if (isOas2) {
+    const produces = producedMediaTypes(document, pathKey);
+    if (produces && !produces.some(isJsonMediaType)) return { schemas, missing };
+    if (isUnresolvedRef(response.schema)) return { schemas, missing };
+    if (isObject(response.schema)) schemas.push({ schema: response.schema, path: [...responsePath, 'schema'] });
+    else missing.push(responsePath);
+    return { schemas, missing };
+  }
+  if (!isObject(response.content) || Object.keys(response.content).length === 0) {
+    missing.push(isObject(response.content) ? [...responsePath, 'content'] : responsePath);
+    return { schemas, missing };
   }
+  Object.entries(response.content)
+    .filter(([mediaTypeName]) => isJsonMediaType(mediaTypeName))
+    .forEach(([mediaTypeName, mediaType]) => {
+      const mediaTypePath = [...responsePath, 'content', mediaTypeName];
+      if (isUnresolvedRef(mediaType) || (isObject(mediaType) && isUnresolvedRef(mediaType.schema))) return;
+      if (isObject(mediaType) && isObject(mediaType.schema)) schemas.push({ schema: mediaType.schema, path: [...mediaTypePath, 'schema'] });
+      else missing.push(mediaTypePath);
+    });
+  return { schemas, missing };
+};
+
+/**
+ * @param {object} response - a resolved response of a GET operation
+ * @param {object} options
+ * @param {string|object} options['paging-schema'] - JSON string or object with the paging structure and its pagingPropertyName (default "paging")
+ * @param {string|string[]} options.paths - comma-separated path patterns matched segment by segment; "*" matches one segment and "**" zero or more (default "/status,/health,/ping,**\/me")
+ * @param {string} options.pathValidationStrategy - "/exclude" (default) skips the matching paths, "/include" only evaluates them
+ * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
+ */
+module.exports = (response, options = {}, context) => {
+  if (!isObject(response) || isUnresolvedRef(response)) return [];
+  const opts = options || {};
+
+  const responsePath = context.path || [];
+  const statusCode = String(responsePath[responsePath.length - 1]);
+  if (!SUCCESS_CODE_REGEX.test(statusCode) || statusCode === NO_CONTENT_CODE) return [];
+
+  const pathKey = typeof responsePath[1] === 'string' ? responsePath[1] : '';
+  if (isDetailPath(pathKey)) return [];
+  const segments = pathKey.split('/');
+  const isListed = pathPatterns(opts.paths).some((pattern) => matchesPattern(pattern, segments));
+  if (isIncludeStrategy(opts.pathValidationStrategy) ? !isListed : isListed) return [];
+
+  const pagingSchema = parsePagingSchema(opts['paging-schema']);
+  const pagingPropertyName = typeof pagingSchema.pagingPropertyName === 'string' && pagingSchema.pagingPropertyName.trim() !== ''
+    ? pagingSchema.pagingPropertyName.trim()
+    : DEFAULT_PAGING_PROPERTY;
+
+  const rawDocument = context.document && context.document.data;
+  const resolvedDocument = context.documentInventory && context.documentInventory.resolved;
+  const document = isObject(resolvedDocument) ? resolvedDocument : rawDocument;
+  const isOas2 = isObject(rawDocument) && typeof rawDocument.swagger === 'string';
+  const ruleCode = context.rule && context.rule.name ? context.rule.name.split(':').pop() : 'OAR034';
+
+  const results = [];
+  const report = (message, path) => results.push({ message: `${ruleCode}: ${message}`, path });
+
+  const { schemas, missing } = evaluatedSchemas(response, responsePath, document, pathKey, isOas2);
+  missing.forEach((path) => report(`Collection response must define a schema with a '${pagingPropertyName}' property`, path));
+
+  schemas.forEach(({ schema, path }) => {
+    const view = buildView(schema, path);
+    const paging = view.properties.get(pagingPropertyName);
+
+    if (!paging) {
+      if (isArrayView(view)) {
+        report(`Collection response must be an object with a '${pagingPropertyName}' property, not a top-level array`, view.path);
+      } else {
+        report(`Collection response must include '${pagingPropertyName}' property for pagination`, view.path);
+      }
+      return;
+    }
+
+    const pagingView = buildView(paging.schema, paging.path);
+    if (!typeMatches('object', pagingView.types)) {
+      report(`'${pagingPropertyName}' must be of type object`, typePath(pagingView));
+      return;
+    }
+    validateAgainstTemplate(pagingSchema, pagingView, pagingPropertyName, report);
+  });
 
   return results;
 };
-
-// Default paging schema matching Java implementation
-const defaultPagingSchema = JSON.stringify({
-  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',
-});

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

@@ -18,9 +18,40 @@ function mergedProperties(schema, visited) {
   return properties;
 }
 
+function parseList(value) {
+  let items = [];
+  if (Array.isArray(value)) {
+    items = value;
+  } else if (typeof value === 'string') {
+    items = value.split(',');
+  }
+  const names = items
+    .filter((item) => typeof item === 'string' || typeof item === 'number')
+    .map((item) => String(item).trim())
+    .filter(Boolean);
+  return [...new Set(names)];
+}
+
+function formatNames(names) {
+  const quoted = names.map((name) => `'${name}'`);
+  if (quoted.length <= 1) {
+    return quoted.join('');
+  }
+  return `${quoted.slice(0, -1).join(', ')} or ${quoted[quoted.length - 1]}`;
+}
+
+function isIncludeStrategy(value) {
+  return typeof value === 'string' && value.trim().replace(/^\//, '').toLowerCase() === 'include';
+}
+
 /**
  * @param {object} given - the 201 response object of a POST operation
  * @param {object} options
+ * @param {string} options['data-property'] - name accepted next to 'error' when allowed-properties is not set (default "data")
+ * @param {string|string[]} options['allowed-properties'] - top-level property names accepted in the schema, array or comma-separated; blank falls back to [data-property, 'error']
+ * @param {string|string[]} options['required-properties'] - top-level property names that must be present, array or comma-separated
+ * @param {string|string[]} options.paths - paths to include/exclude (exact match), array or comma-separated
+ * @param {string} options.pathValidationStrategy - "/include" or "/exclude" (default "/exclude")
  * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
  */
 module.exports = (given, options, context) => {
@@ -28,17 +59,28 @@ module.exports = (given, options, context) => {
     return [];
   }
 
-  const dataProperty = (options && options['data-property']) || 'data';
-  const VALID_NAMES = [dataProperty, 'error'];
+  const opts = options || {};
+  const basePath = context.path || [];
+
+  const paths = parseList(opts.paths);
+  const isListed = paths.includes(basePath[1]);
+  if (isIncludeStrategy(opts.pathValidationStrategy) ? !isListed : isListed) {
+    return [];
+  }
+
+  const dataProperty = opts['data-property'] || 'data';
+  const configuredNames = parseList(opts['allowed-properties']);
+  const allowedNames = configuredNames.length > 0 ? configuredNames : [...new Set([dataProperty, 'error'])];
+  const requiredNames = parseList(opts['required-properties']);
+  const allowedText = formatNames(allowedNames);
   const doc = context.document?.data ?? {};
   const isOAP2 = typeof doc.swagger === 'string';
-  const basePath = context.path || [];
   const errors = [];
 
   const checkSchema = (schema, schemaPath) => {
     if (!schema || typeof schema !== 'object') {
       errors.push({
-        message: `OAR038: 201 response must define a schema with a '${dataProperty}' or 'error' property.`,
+        message: `OAR038: 201 response must define a schema with a ${allowedText} property.`,
         path: schemaPath,
       });
       return;
@@ -49,16 +91,16 @@ module.exports = (given, options, context) => {
 
     if (propNames.length === 0) {
       errors.push({
-        message: `OAR038: Response schema must have properties named '${dataProperty}' or 'error'.`,
+        message: `OAR038: Response schema must have properties named ${allowedText}.`,
         path: schemaPath,
       });
       return;
     }
 
     for (const propName of propNames) {
-      if (!VALID_NAMES.includes(propName)) {
+      if (!allowedNames.includes(propName)) {
         errors.push({
-          message: `OAR038: Response property must be named '${dataProperty}' or 'error'. Got '${propName}'.`,
+          message: `OAR038: Response property must be named ${allowedText}. Got '${propName}'.`,
           path: [...schemaPath, 'properties', propName],
         });
         continue;
@@ -71,6 +113,15 @@ module.exports = (given, options, context) => {
         });
       }
     }
+
+    for (const requiredName of requiredNames) {
+      if (!Object.prototype.hasOwnProperty.call(properties, requiredName)) {
+        errors.push({
+          message: `OAR038: Response schema must define the required property '${requiredName}'.`,
+          path: schemaPath,
+        });
+      }
+    }
   };
 
   if (isOAP2) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "api-quality-spectral-ruleset",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "Spectral ruleset by API Quality",
   "main": "apq-spectral.yaml",
   "files": [
@@ -22,7 +22,7 @@
   "license": "GNU AGPLv3",
   "repository": {
     "type": "git",
-    "url": "https://github.com/apiaddicts/apquality-spectral"
+    "url": "https://github.com/apiaddicts/apiaddicts-style-guide-spectral"
   },
   "devDependencies": {
     "@stoplight/spectral-core": "1.23.0",