@aep_dev/aep-openapi-linter 0.5.1

package/aep/0134.yaml

@@ -0,0 +1,124 @@
+aliases:
+  UpdateOperation:
+    description: An Update method is a patch on path that ends in a path parameter
+    targets:
+      - formats: ['oas2', 'oas3']
+        given:
+          - $.paths[?(@property.match(/\}$/))].patch
+
+rules:
+  aep-134-content-type:
+    description: The request body content type should be "application/merge-patch+json"
+    severity: warn
+    formats: ['oas3']
+    given: '#UpdateOperation'
+    then:
+      field: requestBody.content.application/merge-patch+json
+      function: truthy
+
+  aep-134-operation-id:
+    description: The operation ID should be Update{resource-singular}.
+    message: The operation ID does not conform to AEP-134
+    severity: error
+    formats: ['oas2', 'oas3']
+    given: '#UpdateOperation'
+    then:
+      function: schema
+      functionOptions:
+        schema:
+          type: object
+          properties:
+            operationId:
+              type: string
+              pattern: '^[Uu][Pp][Dd][Aa][Tt][Ee][A-Z].*$'
+          required: ['operationId']
+
+  aep-134-request-body:
+    description: A standard update method must accept the resource in the request body.
+    message: The request body is not an AEP resource.
+    severity: error
+    formats: ['oas3']
+    given: '#UpdateOperation'
+    then:
+      function: schema
+      functionOptions:
+        schema:
+          type: object
+          required: ['requestBody']
+          properties:
+            requestBody:
+              # I tried putting this schema is a separate file and $ref'ing it, but it didn't work
+              description: A content object with an AEP resource schema.
+              type: object
+              required: ['content']
+              properties:
+                content:
+                  type: object
+                  additionalProperties:
+                    type: object
+                    required: ['schema']
+                    properties:
+                      schema:
+                        type: object
+                        required: ['x-aep-resource']
+
+  aep-134-required-params:
+    description: A standard update method must not have any required parameters other than path parameters.
+    severity: error
+    formats: ['oas2', 'oas3']
+    given:
+      - '#UpdateOperation.parameters[?(@.in != "path")]'
+      - '#UpdateOperation^.parameters[?(@.in != "path")]' # parameters at path item level
+    then:
+      field: required
+      function: falsy
+
+  aep-134-response-body:
+    description: The success response for a standard Update method must be the updated AEP resource.
+    message: The response body is not an AEP resource.
+    severity: error
+    formats: ['oas3']
+    given: '#UpdateOperation'
+    then:
+      function: schema
+      functionOptions:
+        schema:
+          type: object
+          required: ['responses']
+          properties:
+            responses:
+              type: object
+              # don't require a 200 response, since it's possible to have a 202
+              properties:
+                '200':
+                  description: A content object with an AEP resource schema.
+                  type: object
+                  required: ['content']
+                  properties:
+                    content:
+                      type: object
+                      additionalProperties:
+                        type: object
+                        required: ['schema']
+                        properties:
+                          schema:
+                            type: object
+                            required: ['x-aep-resource']
+
+  aep-134-unknown-optional-params:
+    description: A standard Update method should not have unknown optional parameters.
+    severity: warn
+    formats: ['oas2', 'oas3']
+    given:
+      - '#UpdateOperation.parameters[?(@.in == "query")]' # only check query parameters
+      - '#UpdateOperation^.parameters[?(@.in == "query")]' # parameters at path item level
+    then:
+      # Use schema function on name so that the error points to the name field
+      function: schema
+      functionOptions:
+        schema:
+          type: object
+          properties:
+            name:
+              # Update has no defined optional parameters
+              enum: [null]

package/aep/0135.yaml

@@ -0,0 +1,49 @@
+aliases:
+  DeleteOperation:
+    description: A Delete operation is a delete on path that ends in a path parameter
+    targets:
+      - formats: ['oas2', 'oas3']
+        given:
+          # first condition excludes custom methods and second condition matches paths ending in a path parameter
+          - $.paths[?(!@property.match(/:[^/]*$/) && @property.match(/\}$/))].delete
+
+rules:
+  aep-135-http-body:
+    description: A delete operation must not accept a request body.
+    severity: error
+    formats: ['oas3']
+    given:
+      - '#DeleteOperation.requestBody'
+    then:
+      function: falsy
+
+  aep-135-operation-id:
+    description: The operation ID should be Delete{resource-singular}.
+    message: The operation ID does not conform to AEP-135
+    severity: error
+    formats: ['oas2', 'oas3']
+    given: '#DeleteOperation'
+    then:
+      function: schema
+      functionOptions:
+        schema:
+          type: object
+          properties:
+            operationId:
+              type: string
+              pattern: '^[Dd][Ee][Ll][Ee][Tt][Ee][A-Z].*$'
+          required: ['operationId']
+
+  aep-135-response-204:
+    description: A delete operation should have a 204 response.
+    message: A delete operation should have a `204` response.
+    severity: warn
+    formats: ['oas2', 'oas3']
+    given: '#DeleteOperation.responses'
+    then:
+      function: schema
+      functionOptions:
+        schema:
+          oneOf:
+            - required: ['204']
+            - required: ['202']

package/aep/0136.yaml

@@ -0,0 +1,53 @@
+aliases:
+  CustomOperation:
+    description: A custom method is identified by a path containing a colon (:) before the verb
+    targets:
+      - formats: ['oas2', 'oas3']
+        given:
+          # condition excludes custom methods Update Array custom operations defined in AEP-144, as different list of rules applies to them
+          - $.paths[?(@property.match(/:(?!add|remove)([^/]*)$/))]
+
+rules:
+  aep-136-http-body:
+    description: GET-based custom methods must have no request body.
+    severity: error
+    formats: ['oas3']
+    given: '#CustomOperation.get.requestBody'
+    then:
+      function: falsy
+
+  aep-136-http-method:
+    description: Custom methods should use POST or GET.
+    severity: warn
+    formats: ['oas2', 'oas3']
+    given: '#CustomOperation'
+    then:
+      function: schema
+      functionOptions:
+        schema:
+          # trigger if any method is not POST or GET
+          not:
+            anyOf:
+              - required: ['delete']
+              - required: ['head']
+              - required: ['options']
+              - required: ['patch']
+              - required: ['put']
+              - required: ['trace']
+
+  aep-136-operation-id:
+    description: The operation ID should start with a colon and a capital letter.
+    message: The operation ID does not conform to AEP-136
+    severity: warn
+    formats: ['oas2', 'oas3']
+    given: '#CustomOperation[*]'
+    then:
+      function: schema
+      functionOptions:
+        schema:
+          type: object
+          properties:
+            operationId:
+              type: string
+              pattern: '^:[A-Z].*$'
+          required: ['operationId']

package/aep/0137.yaml

@@ -0,0 +1,115 @@
+aliases:
+  ApplyOperation:
+    description: An Apply method is a put on path that ends in a path parameter
+    targets:
+      - formats: ['oas2', 'oas3']
+        given:
+          - $.paths[?(@property.match(/\}$/))].put
+
+rules:
+  aep-137-operation-id:
+    description: The operation ID should be Apply{resource-singular}.
+    message: The operation ID does not conform to AEP-137
+    severity: error
+    formats: ['oas2', 'oas3']
+    given: '#ApplyOperation'
+    then:
+      function: schema
+      functionOptions:
+        schema:
+          type: object
+          properties:
+            operationId:
+              type: string
+              pattern: '^[Aa][Pp][Pp][Ll][Yy].*$'
+          required: ['operationId']
+
+  aep-137-request-body:
+    description: A standard Apply method must accept the resource in the request body.
+    message: The request body is not an AEP resource.
+    severity: error
+    formats: ['oas3']
+    given: '#ApplyOperation'
+    then:
+      function: schema
+      functionOptions:
+        schema:
+          type: object
+          required: ['requestBody']
+          properties:
+            requestBody:
+              # I tried putting this schema is a separate file and $ref'ing it, but it didn't work
+              description: A content object with an AEP resource schema.
+              type: object
+              required: ['content']
+              properties:
+                content:
+                  type: object
+                  additionalProperties:
+                    type: object
+                    required: ['schema']
+                    properties:
+                      schema:
+                        type: object
+                        required: ['x-aep-resource']
+
+  aep-137-required-params:
+    description: A standard Apply method must not have any required parameters other than path parameters.
+    severity: error
+    formats: ['oas2', 'oas3']
+    given:
+      - '#ApplyOperation.parameters[?(@.in != "path")]'
+      - '#ApplyOperation^.parameters[?(@.in != "path")]' # parameters at path item level
+    then:
+      field: required
+      function: falsy
+
+  aep-137-response-body:
+    description: The success response for a standard Apply method must be the AEP resource.
+    message: The response body is not an AEP resource.
+    severity: error
+    formats: ['oas3']
+    given: '#ApplyOperation'
+    then:
+      function: schema
+      functionOptions:
+        schema:
+          type: object
+          required: ['responses']
+          properties:
+            responses:
+              type: object
+              # don't require a 200 response, since it's possible to have a 202
+              properties:
+                '200':
+                  description: A content object with an AEP resource schema.
+                  type: object
+                  required: ['content']
+                  properties:
+                    content:
+                      type: object
+                      additionalProperties:
+                        type: object
+                        required: ['schema']
+                        properties:
+                          schema:
+                            type: object
+                            required: ['x-aep-resource']
+
+  aep-137-unknown-optional-params:
+    description: A standard Apply method should not have unknown optional parameters.
+    severity: warn
+    formats: ['oas2', 'oas3']
+    given:
+      - '#ApplyOperation.parameters[?(@.in == "query")]' # only check query parameters
+      - '#ApplyOperation^.parameters[?(@.in == "query")]' # parameters at path item level
+    then:
+      # Use schema function on name so that the error points to the name field
+      function: schema
+      functionOptions:
+        schema:
+          type: object
+          properties:
+            name:
+              # Apply has no defined optional parameters
+              enum: [null]

package/aep/0140.yaml

@@ -0,0 +1,17 @@
+rules:
+  aep-140-boolean-property-naming:
+    description: 'Boolean properties should omit the prefix "is".'
+    severity: warn
+    given: '$..[?(@.type == "boolean")]~'
+    then:
+      field: '@key'
+      function: pattern
+      functionOptions:
+        notMatch: '^[Ii][Ss]_?[A-Za-z0-9_-]*$'
+
+  aep-140-uri-property-naming:
+    description: 'Properties representing URLs or URIs should be named "uri" rather than "url".'
+    severity: warn
+    given: '$..[?(@.type == "string" && (@property.match(/url$/)))]~'
+    then:
+      function: falsy

package/aep/0142.yaml

@@ -0,0 +1,37 @@
+functionsDir: ../functions
+functions:
+  - aep-142-time-field-type
+
+rules:
+  aep-142-time-field-type:
+    description: 'Fields with time-related suffixes should use appropriate types and formats.'
+    message: '{{error}}'
+    severity: warn
+    formats: ['oas2', 'oas3']
+    given: '$..properties[?(@property.match(/_(time|times|date|seconds|millis|micros|nanos)$/))]'
+    then:
+      function: aep-142-time-field-type
+
+  aep-142-time-field-names:
+    description: 'Timestamp fields should use imperative mood with _time suffix, not past tense.'
+    message: 'Use imperative mood with "_time" suffix (e.g., "{{property}}_time") instead of past tense.'
+    severity: warn
+    formats: ['oas2', 'oas3']
+    given: '$..[?(@.type == "string" && @.format == "date-time")]~'
+    then:
+      field: '@key'
+      function: pattern
+      functionOptions:
+        notMatch: '(created|creation|updated|modified|expired|purged|deleted|published|started|ended|completed)'
+
+  aep-142-time-field-suffix:
+    description: 'Timestamp fields must end in _time suffix.'
+    message: 'Timestamp field "{{property}}" should end with "_time" suffix.'
+    severity: warn
+    formats: ['oas2', 'oas3']
+    given: '$..[?(@.type == "string" && @.format == "date-time")]~'
+    then:
+      field: '@key'
+      function: pattern
+      functionOptions:
+        match: '_time$'

package/aep/0143.yaml

@@ -0,0 +1,31 @@
+functionsDir: ../functions
+functions:
+  - standardized-codes
+
+rules:
+  aep-143-standardized-codes:
+    description: Field names for standardized codes must follow AEP-143 conventions.
+    message: '{{error}}'
+    severity: error
+    formats: ['oas2', 'oas3']
+    given: $.components.schemas[*]
+    then:
+      function: standardized-codes
+
+  aep-143-standardized-codes-string-type:
+    description: Standardized code fields must be of type "string".
+    message: 'Standardized code field "{{property}}" must be type "string"'
+    severity: error
+    formats: ['oas2', 'oas3']
+    given:
+      - $.components.schemas[*].properties[?(@property in ['content_type', 'currency_code', 'language_code'])]
+      - $.components.schemas[*].properties[?(@property in ['region_code', 'time_zone', 'utc_offset'])]
+    then:
+      function: schema
+      functionOptions:
+        schema:
+          type: object
+          required: ['type']
+          properties:
+            type:
+              const: string

package/aep/0144.yaml

@@ -0,0 +1,39 @@
+aliases:
+  AddRemovePathItem:
+    description: An Update Array operation is a post request that updates an array with add or remove operation
+    targets:
+      - formats: ['oas2', 'oas3']
+        given:
+          - $.paths[?(@property.match(/:(add|remove)([^/]*)$/))]
+
+rules:
+  aep-144-operation-id:
+    description: The operation ID must begin with the word add or remove.
+    message: The operation ID does not conform to AEP-144.
+    severity: error
+    formats: ['oas2', 'oas3']
+    given: '#AddRemovePathItem[*].operationId'
+    then:
+      function: pattern
+      functionOptions:
+        match: '^([Aa]dd|[Rr]emove)[A-Z].*$'
+
+  aep-144-http-method:
+    description: An Update Array operation must be POST.
+    severity: error
+    formats: ['oas2', 'oas3']
+    given: '#AddRemovePathItem'
+    then:
+      function: schema
+      functionOptions:
+        schema:
+          # trigger if any method is not POST
+          not:
+            anyOf:
+              - required: ['delete']
+              - required: ['get']
+              - required: ['head']
+              - required: ['options']
+              - required: ['patch']
+              - required: ['put']
+              - required: ['trace']

package/aep/0151.yaml

@@ -0,0 +1,94 @@
+aliases:
+  LongRunningOperation:
+    description: An operation that returns 202 Accepted for long-running operations
+    targets:
+      - formats: ['oas2', 'oas3']
+        given:
+          - $.paths[*].[post,put,patch,delete].responses.202^^
+
+functionsDir: ../functions
+functions:
+  - operations-endpoint
+
+rules:
+  aep-151-202-only-success:
+    description: Long-running operations must return 202 as the only success status code
+    message: Long-running operations must return 202 as the only success status code
+    severity: error
+    formats: ['oas2', 'oas3']
+    given:
+      - '#LongRunningOperation.responses'
+    then:
+      function: schema
+      functionOptions:
+        schema:
+          not:
+            anyOf:
+              - required: ['200']
+              - required: ['201']
+              - required: ['204']
+
+  aep-151-202-schema-required:
+    description: A 202 response must define an application/json response body with Operation schema
+    severity: error
+    formats: ['oas3']
+    given:
+      - '#LongRunningOperation.responses.202'
+    then:
+      function: schema
+      functionOptions:
+        schema:
+          type: object
+          required: ['content']
+          properties:
+            content:
+              type: object
+              required: ['application/json']
+              properties:
+                'application/json':
+                  type: object
+                  required: ['schema']
+
+  aep-151-operation-schema:
+    description: Operation schema must have correct property types
+    message: Operation schema must have correct property types
+    severity: error
+    formats: ['oas3']
+    given:
+      - '#LongRunningOperation.responses.202.content.application/json.schema'
+    then:
+      function: schema
+      functionOptions:
+        schema:
+          type: object
+          required: ['properties']
+          properties:
+            properties:
+              type: object
+              required: ['path', 'done', 'error', 'response']
+              properties:
+                path:
+                  type: object
+                  required: ['type']
+                  properties:
+                    type:
+                      enum: ['string']
+                done:
+                  type: object
+                  required: ['type']
+                  properties:
+                    type:
+                      enum: ['boolean']
+                error:
+                  type: object
+                response:
+                  type: object
+
+  aep-151-operations-endpoint:
+    description: Services with long-running operations must define an operations endpoint
+    message: '{{error}}'
+    severity: error
+    formats: ['oas2', 'oas3']
+    given: $.paths
+    then:
+      function: operations-endpoint