@aep_dev/aep-openapi-linter 0.5.1

package/aep/0158.yaml

@@ -0,0 +1,175 @@
+aliases:
+  ListOperation:
+    description: A list operation is a get on path that does not end in a path parameter
+    targets:
+      - formats: ['oas2', 'oas3']
+        given:
+          # first condition excludes custom methods and second condition excludes paths ending in a path parameter
+          - $.paths[?(!@property.match(/:[^/]*$/) && !@property.match(/\}$/))].get
+
+functionsDir: ../functions
+functions:
+  - skipSingletonsSchema
+
+rules:
+  aep-158-max-page-size-parameter:
+    description: Operations that return collections should define an integer max_page_size parameter.
+    severity: warn
+    formats: ['oas3']
+    given:
+      - '#ListOperation'
+    then:
+      function: skipSingletonsSchema
+      functionOptions:
+        schema:
+          type: object
+          required: ['parameters']
+          properties:
+            parameters:
+              type: array
+              contains:
+                type: object
+                required: ['name', 'schema']
+                properties:
+                  name:
+                    enum: ['max_page_size']
+                  schema:
+                    type: object
+                    required: ['type']
+                    properties:
+                      type:
+                        enum: ['integer']
+
+  aep-158-page-token-parameter:
+    description: Operations that return collections should define a string page_token parameter.
+    severity: warn
+    formats: ['oas3']
+    given:
+      - '#ListOperation'
+    then:
+      function: skipSingletonsSchema
+      functionOptions:
+        schema:
+          type: object
+          required: ['parameters']
+          properties:
+            parameters:
+              type: array
+              contains:
+                type: object
+                required: ['name', 'schema']
+                properties:
+                  name:
+                    enum: ['page_token']
+                  schema:
+                    type: object
+                    required: ['type']
+                    properties:
+                      type:
+                        enum: ['string']
+
+  aep-158-page-token-parameter-optional:
+    description: The page_token parameter must not be required.
+    severity: error
+    formats: ['oas3']
+    given:
+      - '#ListOperation.parameters[?(@.name == "page_token")]'
+    then:
+      function: schema
+      functionOptions:
+        schema:
+          type: object
+          properties:
+            required:
+              not:
+                enum: [true]
+
+  aep-158-response-array-property:
+    description: The response schema must include an array property.
+    severity: error
+    formats: ['oas3']
+    given:
+      - '#ListOperation.responses.200.content.application/json.schema'
+    then:
+      function: schema
+      functionOptions:
+        schema:
+          type: object
+          anyOf:
+            - required: ['properties']
+              properties:
+                properties:
+                  # You can use this pattern to get an object contains constraint
+                  type: object
+                  not:
+                    additionalProperties:
+                      not:
+                        type: object
+                        required: ['type']
+                        properties:
+                          type:
+                            enum: ['array']
+            - # Ignore for singleton resources
+              required: ['x-aep-resource']
+              properties:
+                'x-aep-resource':
+                  type: object
+                  required: ['singleton']
+                  properties:
+                    'singleton':
+                      enum: [true]
+
+  aep-158-response-next-page-token-property:
+    description: The response schema must include a string next_page_token property.
+    severity: error
+    formats: ['oas3']
+    given:
+      - '#ListOperation.responses.200.content.application/json.schema'
+    then:
+      function: schema
+      functionOptions:
+        schema:
+          type: object
+          anyOf:
+            - required: ['properties']
+              properties:
+                properties:
+                  type: object
+                  required: ['next_page_token']
+                  properties:
+                    next_page_token:
+                      type: object
+                      required: ['type']
+                      properties:
+                        type:
+                          enum: ['string']
+            - # Ignore for singleton resources
+              required: ['x-aep-resource']
+              properties:
+                'x-aep-resource':
+                  type: object
+                  required: ['singleton']
+                  properties:
+                    'singleton':
+                      enum: [true]
+
+  aep-158-skip-parameter:
+    description: Operations that return collections may define an integer skip parameter.
+    message: The skip parameter must be an integer.
+    severity: warn
+    formats: ['oas3']
+    given:
+      - '#ListOperation.parameters[?(@.name == "skip")]'
+    then:
+      function: schema
+      functionOptions:
+        schema:
+          type: object
+          required: ['schema']
+          properties:
+            schema:
+              type: object
+              required: ['type']
+              properties:
+                type:
+                  enum: ['integer']

package/aep/0193.yaml

@@ -0,0 +1,54 @@
+rules:
+  aep-193-error-response-schema:
+    description: Error response body should contain all required fields according to AEP-193.
+    message: '{{error}}'
+    severity: warn
+    formats: ['oas2', 'oas3']
+    given: $.paths[*][*].responses[?(@property >= 400)].content[*].schema.properties
+    then:
+      function: schema
+      functionOptions:
+        schema:
+          type: object
+          required: ['type']
+          properties:
+            type:
+              type: object
+              required: ['type', 'format']
+              properties:
+                type:
+                  enum: ['string']
+                format:
+                  enum: ['uri-reference']
+            title:
+              type: object
+              required: ['type']
+              properties:
+                type:
+                  enum: ['string']
+            status:
+              type: object
+              required: ['type']
+              properties:
+                type:
+                  enum: ['integer']
+                minimum:
+                  type: integer
+                  minimum: 100
+                maximum:
+                  type: integer
+                  maximum: 599
+            detail:
+              type: object
+              required: ['type']
+              properties:
+                type:
+                  enum: ['string']
+            instance:
+              type: object
+              required: ['type', 'format']
+              properties:
+                type:
+                  enum: ['string']
+                format:
+                  enum: ['uri-reference']

package/functions/aep-142-time-field-type.js

@@ -0,0 +1,107 @@
+/**
+ * Validates that fields with time-related suffixes use the correct OpenAPI types.
+ *
+ * Based on AEP-142 specification (https://aep.dev/142).
+ *
+ * AEP-documented suffixes and their expected types:
+ * - _time, _times → string with format: date-time (RFC 3339)
+ * - _date → string with format: date
+ * - _seconds → integer or number
+ * - _millis → integer or number
+ * - _micros → integer or number
+ * - _nanos → integer or number
+ *
+ * @param {object} field - The field object being validated
+ * @param {object} _opts - Options (unused)
+ * @param {object} context - Spectral context containing the path
+ * @returns {Array<object>} Array of error objects, or empty array if valid
+ */
+module.exports = (field, _opts, context) => {
+  if (!field || typeof field !== 'object') {
+    return [];
+  }
+
+  // Extract the field name from the path - it should be the last element
+  // path looks like:
+  // ['paths', '/test', 'get', 'responses', '200', 'content',
+  //  'application/json', 'schema', 'properties', 'create_time']
+  const path = context.path || [];
+  const fieldName = path[path.length - 1];
+
+  if (typeof fieldName !== 'string' || !fieldName.includes('_')) {
+    return [];
+  }
+
+  // Extract the suffix (last word after underscore)
+  const parts = fieldName.split('_');
+  const suffix = parts[parts.length - 1];
+
+  // Define suffix categories and their expected types (AEP-142 documented only)
+  const timestampSuffixes = ['time', 'times'];
+  const dateSuffixes = ['date'];
+  const durationSecondSuffixes = ['seconds'];
+  const durationMilliSuffixes = ['millis'];
+  const durationMicroSuffixes = ['micros'];
+  const durationNanoSuffixes = ['nanos'];
+
+  const allSuffixes = [
+    ...timestampSuffixes,
+    ...dateSuffixes,
+    ...durationSecondSuffixes,
+    ...durationMilliSuffixes,
+    ...durationMicroSuffixes,
+    ...durationNanoSuffixes,
+  ];
+
+  // Check if this field has a time-related suffix
+  if (!allSuffixes.includes(suffix)) {
+    return [];
+  }
+
+  const errors = [];
+
+  // Validate timestamp fields (_time, _times)
+  if (timestampSuffixes.includes(suffix)) {
+    // For _times (plural), allow arrays of timestamps
+    if (suffix === 'times' && field.type === 'array') {
+      // Check that array items are strings with date-time format
+      if (!field.items || field.items.type !== 'string' || field.items.format !== 'date-time') {
+        errors.push({
+          message:
+            `Field "${fieldName}" should be an array with items of type "string" ` +
+            `and format "date-time" (RFC 3339 timestamp).`,
+        });
+      }
+    } else if (field.type !== 'string' || field.format !== 'date-time') {
+      errors.push({
+        message: `Field "${fieldName}" should have type "string" and format "date-time" (RFC 3339 timestamp).`,
+      });
+    }
+  }
+
+  // Validate date fields (_date)
+  else if (dateSuffixes.includes(suffix)) {
+    if (field.type !== 'string' || field.format !== 'date') {
+      errors.push({
+        message: `Field "${fieldName}" should have type "string" and format "date" (RFC 3339 date).`,
+      });
+    }
+  }
+
+  // Validate duration fields (seconds, millis, micros, nanos)
+  else if (
+    durationSecondSuffixes.includes(suffix) ||
+    durationMilliSuffixes.includes(suffix) ||
+    durationMicroSuffixes.includes(suffix) ||
+    durationNanoSuffixes.includes(suffix)
+  ) {
+    // Duration fields should be integers (or numbers for fractional values)
+    if (field.type !== 'integer' && field.type !== 'number') {
+      errors.push({
+        message: `Field "${fieldName}" should have type "integer" or "number" for duration values.`,
+      });
+    }
+  }
+
+  return errors;
+};

package/functions/operations-endpoint.js

@@ -0,0 +1,40 @@
+// Check that services with long-running operations (202 responses) have the required operations endpoints
+
+module.exports = (paths, _opts, context) => {
+  if (!paths || typeof paths !== 'object') {
+    return [];
+  }
+
+  const errors = [];
+  const pathKeys = Object.keys(paths);
+
+  // Check if any path has a 202 response
+  const hasLongRunningOperation = pathKeys.some((pathKey) => {
+    const pathItem = paths[pathKey];
+    if (!pathItem || typeof pathItem !== 'object') return false;
+
+    // Check all HTTP methods that can have 202 responses
+    const methods = ['post', 'put', 'patch', 'delete'];
+    return methods.some(
+      (method) => pathItem[method] && pathItem[method].responses && pathItem[method].responses['202']
+    );
+  });
+
+  // If no long-running operations, no need to check for operations endpoints
+  if (!hasLongRunningOperation) {
+    return [];
+  }
+
+  // Check for required operations endpoints
+  const hasOperationsList = paths['/v1/operations'] && paths['/v1/operations'].get;
+  const hasOperationsGet = paths['/v1/operations/{operation}'] && paths['/v1/operations/{operation}'].get;
+
+  if (!hasOperationsList || !hasOperationsGet) {
+    errors.push({
+      message: 'Services with long-running operations must define an operations endpoint with list and get operations',
+      path: context.path || ['paths'],
+    });
+  }
+
+  return errors;
+};

package/functions/parameter-names-unique.js

@@ -0,0 +1,78 @@
+// Check that the parameters of an operation -- including those specified on the path -- are
+// are case-insensitive unique regardless of "in".
+
+// Return the "canonical" casing for a string.
+// Currently just lowercase but should be extended to convert kebab/camel/snake/Pascal.
+function canonical(name) {
+  return typeof name === 'string' ? name.toLowerCase() : name;
+}
+
+// Accept an array and return a list of unique duplicate entries in canonical form.
+// This function is intended to work on strings but is resilient to non-strings.
+function dupIgnoreCase(arr) {
+  if (!Array.isArray(arr)) {
+    return [];
+  }
+
+  const isDup = (value, index, self) => self.indexOf(value) !== index;
+
+  return [...new Set(arr.map((v) => canonical(v)).filter(isDup))];
+}
+
+// targetVal should be a
+// [path item object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#pathItemObject).
+// The code assumes it is running on a resolved doc
+module.exports = (pathItem, _opts, paths) => {
+  if (pathItem === null || typeof pathItem !== 'object') {
+    return [];
+  }
+  const path = paths.path || paths.target || [];
+
+  const errors = [];
+
+  const pathParams = pathItem.parameters ? pathItem.parameters.map((p) => p.name) : [];
+
+  // Check path params for dups
+  const pathDups = dupIgnoreCase(pathParams);
+
+  // Report all dups
+  pathDups.forEach((dup) => {
+    // get the index of all names that match dup
+    const dupKeys = [...pathParams.keys()].filter((k) => canonical(pathParams[k]) === dup);
+    // Report errors for all the others
+    dupKeys.slice(1).forEach((key) => {
+      errors.push({
+        message: `Duplicate parameter name (ignoring case): ${dup}.`,
+        path: [...path, 'parameters', key, 'name'],
+      });
+    });
+  });
+
+  ['get', 'post', 'put', 'patch', 'delete', 'options', 'head'].forEach((method) => {
+    // If this method exists and it has parameters, check them
+    if (pathItem[method] && Array.isArray(pathItem[method].parameters)) {
+      const allParams = [...pathParams, ...pathItem[method].parameters.map((p) => p.name)];
+
+      // Check method params for dups -- including path params
+      const dups = dupIgnoreCase(allParams);
+
+      // Report all dups
+      dups.forEach((dup) => {
+        // get the index of all names that match dup
+        const dupKeys = [...allParams.keys()].filter((k) => canonical(allParams[k]) === dup);
+        // Report errors for any others that are method parameters
+        dupKeys
+          .slice(1)
+          .filter((k) => k >= pathParams.length)
+          .forEach((key) => {
+            errors.push({
+              message: `Duplicate parameter name (ignoring case): ${dup}.`,
+              path: [...path, method, 'parameters', key - pathParams.length, 'name'],
+            });
+          });
+      });
+    }
+  });
+
+  return errors;
+};

package/functions/singleton-utils.js

@@ -0,0 +1,87 @@
+// Shared utility functions for singleton resource validation
+// according to AEP-156 specifications
+
+/**
+ * Normalize a path or pattern: ensure leading slash, no duplicate slashes
+ * @param {string} str
+ * @returns {string}
+ */
+function normalizePath(str) {
+  if (!str) return '';
+  // Remove leading/trailing whitespace, ensure leading slash, remove duplicate slashes
+  let s = str.trim();
+  if (!s.startsWith('/')) s = `/${s}`;
+  s = s.replace(/\/+/g, '/');
+  return s;
+}
+
+/**
+ * Get all singleton resource patterns from the OAS document
+ * @param {Object} oasDoc - The OpenAPI document
+ * @returns {Array} Array of singleton patterns
+ */
+function getSingletonPatterns(oasDoc) {
+  if (!oasDoc || !oasDoc.components || !oasDoc.components.schemas) {
+    return [];
+  }
+  const singletonPatterns = [];
+  const { schemas } = oasDoc.components;
+  Object.values(schemas).forEach((schema) => {
+    if (
+      schema &&
+      schema['x-aep-resource'] &&
+      schema['x-aep-resource'].singleton === true &&
+      Array.isArray(schema['x-aep-resource'].patterns)
+    ) {
+      singletonPatterns.push(...schema['x-aep-resource'].patterns);
+    }
+  });
+  return singletonPatterns;
+}
+
+/**
+ * Check if a path string matches any singleton pattern exactly
+ * @param {string} pathString - The path to check
+ * @param {Object} oasDoc - The OpenAPI document
+ * @returns {boolean} True if the path matches a singleton pattern
+ */
+function pathMatchesSingletonPattern(pathString, oasDoc) {
+  if (!pathString) return false;
+  const normalizedPath = normalizePath(pathString);
+  const singletonPatterns = getSingletonPatterns(oasDoc);
+  return singletonPatterns.some((pattern) => {
+    const normalizedPattern = normalizePath(pattern);
+    const regexPattern = `^${normalizedPattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&').replace(/\{[^/]+\}/g, '[^/]+')}$`;
+    const regex = new RegExp(regexPattern);
+    return regex.test(normalizedPath);
+  });
+}
+
+/**
+ * Check if a path string matches a singleton list pattern
+ * @param {string} pathString - The path to check
+ * @param {Object} oasDoc - The OpenAPI document
+ * @returns {boolean} True if the path matches a singleton list pattern
+ */
+function pathMatchesSingletonListPattern(pathString, oasDoc) {
+  if (!pathString) return false;
+  const normalizedPath = normalizePath(pathString);
+  const singletonPatterns = getSingletonPatterns(oasDoc);
+  return singletonPatterns.some((pattern) => {
+    // Convert singleton pattern to list pattern: {parent}/{parent-id}/{singleton} -> {parent}/-/configs
+    const listPattern = pattern.replace(/\/[^/]+$/, '/-/configs');
+    const normalizedListPattern = normalizePath(listPattern);
+    const regexPattern = `^${normalizedListPattern
+      .replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+      .replace(/\{[^/]+\}/g, '[^/]+')}$`;
+    const regex = new RegExp(regexPattern);
+    return regex.test(normalizedPath);
+  });
+}
+
+module.exports = {
+  getSingletonPatterns,
+  pathMatchesSingletonPattern,
+  pathMatchesSingletonListPattern,
+  normalizePath,
+};

package/functions/skipSingletonsSchema.js

@@ -0,0 +1,35 @@
+// This function first checks if the target operation is for a singleton resource
+// by looking for the `x-aep-resource` extension with `singleton: true`.
+// If it is a singleton, it does not report any errors.
+// Otherwise, it performs validation of the target using the `schema` specified in the function parameters.
+
+// Spectral allows custom functions to invoke core functions.
+// The documentation for this feature can be found at:
+// https://docs.stoplight.io/docs/spectral/a781e290eb9f9-custom-functions#referencing-core-functions
+// This function uses the `schema` function from Spectral to validate the operation object.
+const { schema: schemaFunction } = require('@stoplight/spectral-functions');
+
+// targetVal should be an operation object.
+// The code assumes it is running on a resolved doc
+module.exports = (op, opts, context) => {
+  if (op === null || typeof op !== 'object') {
+    return [];
+  }
+
+  // opts must contain a schema to validate the operation against
+  if (opts === null || typeof opts !== 'object' || !opts.schema) {
+    return [];
+  }
+
+  // Check if the operation is for a singleton resource
+  const responseSchema = op.responses?.['200']?.content?.['application/json']?.schema;
+  if (responseSchema?.['x-aep-resource']?.singleton) {
+    return []; // No errors for singleton resources
+  }
+
+  // The operation is not for a singleton resource, apply the schema to the operation
+  // and return any errors found
+  const schemaErrors = schemaFunction(op, opts, context);
+
+  return schemaErrors;
+};

package/functions/standardized-codes.js

@@ -0,0 +1,50 @@
+// Validates that standardized code field names follow AEP-143 conventions.
+// Checks schema property names and suggests correct standardized field names.
+
+// Map of incorrect field name variants to their correct standardized names
+const fieldNameVariants = {
+  // Content/Media types
+  mime: 'content_type',
+  mimetype: 'content_type',
+  mime_type: 'content_type',
+  media_type: 'content_type',
+  mediatype: 'content_type',
+  // Countries/Regions
+  country: 'region_code',
+  country_code: 'region_code',
+  region: 'region_code',
+  // Currency
+  currency: 'currency_code',
+  // Language
+  lang: 'language_code',
+  language: 'language_code',
+  locale: 'language_code',
+  // Time zones
+  tz: 'time_zone',
+  timezone: 'time_zone',
+};
+
+// targetVal is a schema object containing properties
+module.exports = (schema, _opts, paths) => {
+  if (!schema || typeof schema !== 'object') {
+    return [];
+  }
+
+  const errors = [];
+  const path = paths.path || paths.target || [];
+
+  // Check if this is a schema with properties
+  if (schema.properties && typeof schema.properties === 'object') {
+    Object.keys(schema.properties).forEach((propertyName) => {
+      const correctName = fieldNameVariants[propertyName];
+      if (correctName) {
+        errors.push({
+          message: `Use "${correctName}" instead of "${propertyName}" for standardized code fields.`,
+          path: [...path, 'properties', propertyName],
+        });
+      }
+    });
+  }
+
+  return errors;
+};

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@aep_dev/aep-openapi-linter",
+  "version": "0.5.1",
+  "description": "Linter for OpenAPI definitions to check compliance to AEPs",
+  "main": "spectral.yaml",
+  "files": [
+    "aep",
+    "functions",
+    "spectral.yaml"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "lint": "prettier --check . && eslint --cache --quiet --ext '.js' functions test",
+    "lint-fix": "prettier --write . && eslint --cache --quiet --ext '.js' --fix functions test",
+    "test": "jest --coverage",
+    "release:patch": "./scripts/prepare-release.sh patch",
+    "release:minor": "./scripts/prepare-release.sh minor",
+    "release:major": "./scripts/prepare-release.sh major"
+  },
+  "author": "Mike Kistler",
+  "license": "MIT",
+  "repository": {
+    "url": "https://github.com/aep-dev/aep-openapi-linter"
+  },
+  "devDependencies": {
+    "@jest/globals": "^29.7.0",
+    "@stoplight/spectral-core": "^1.20.0",
+    "@stoplight/spectral-parsers": "^1.0.5",
+    "@stoplight/spectral-ruleset-migrator": "^1.11.1",
+    "@stoplight/spectral-rulesets": "^1.21.3",
+    "ajv": "^8.6.2",
+    "eslint": "^8.57.0",
+    "eslint-config-airbnb-base": "^15.0.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-import": "^2.23.4",
+    "jest": "^29.7.0",
+    "prettier": "^3.2.5"
+  },
+  "jest": {
+    "collectCoverage": true,
+    "collectCoverageFrom": [
+      "functions/*.js"
+    ],
+    "coverageThreshold": {
+      "./functions/*.js": {
+        "statements": 80
+      }
+    },
+    "moduleNameMapper": {
+      "^nimma/legacy$": "<rootDir>/node_modules/nimma/dist/legacy/cjs/index.js",
+      "^nimma/(.*)": "<rootDir>/node_modules/nimma/dist/cjs/$1",
+      "^@stoplight/spectral-ruleset-bundler/(.*)$": "<rootDir>/node_modules/@stoplight/spectral-ruleset-bundler/dist/$1"
+    }
+  },
+  "dependencies": {
+    "@stoplight/spectral-functions": "^1.10.1"
+  }
+}