@aep_dev/aep-openapi-linter 0.5.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Mike Kistler
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,64 @@
+# aep-openapi-linter
+
+Linter for OpenAPI definitions to check compliance to [AEPs].
+
+This repository contains a [Spectral](https://github.com/stoplightio/spectral)
+ruleset to check an [OpenAPI] document for conformance to the [API Enhancement
+Proposals].
+
+[AEPs]: https://aep.dev
+[API Enhancement Proposals]: https://aep.dev
+[OpenAPI]: https://www.openapis.org/
+
+## How to use the aep-openapi-linter
+
+### Dependencies
+
+The Spectral Ruleset requires Node version 20 or later.
+
+### Install Spectral
+
+`npm i @stoplight/spectral-cli -g`
+
+### Usage
+
+You can specify the ruleset directly on the command line:
+
+`spectral lint -r https://raw.githubusercontent.com/aep-dev/aep-openapi-linter/main/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/aep-dev/aep-openapi-linter/main/spectral.yaml
+```
+
+### Example
+
+```bash
+spectral lint -r https://raw.githubusercontent.com/aep-dev/aep-openapi-linter/main/spectral.yaml petstore.yaml
+```
+
+### Using the Spectral VSCode extension
+
+There is a
+[Spectral VSCode extension](https://marketplace.visualstudio.com/items?itemName=stoplight.spectral)
+that will run the Spectral linter on an open API definition file and show
+errors right within VSCode. You can use this ruleset with the Spectral VSCode
+extension.
+
+1. Install the Spectral VSCode extension from the extensions tab in VSCode.
+2. Create a Spectral configuration file (`.spectral.yaml`) in the root
+   directory of your project as shown above.
+3. Set `spectral.rulesetFile` to the name of this configuration file in your
+   VSCode settings.
+
+Now when you open an OpenAPI document in this project, it should highlight
+lines with errors. You can also get a full list of problems in the file by
+opening the "Problems panel" with "View / Problems". In the Problems panel you
+can filter to show or hide errors, warnings, or infos.
+
+## Contributing
+
+See [CONTRIBUTING](./CONTRIBUTING.md) for more details.

package/aep/0004.yaml

@@ -0,0 +1,38 @@
+rules:
+  aep-0004-x-aep-resource-structure:
+    description: x-aep-resource must have correct structure with required fields (singular, plural)
+    message: The x-aep-resource extension does not conform to AEP-4 requirements
+    severity: error
+    formats: ['oas2', 'oas3']
+    given: $.components.schemas[?(@['x-aep-resource'] && @['x-aep-resource'] != true)]
+    then:
+      field: x-aep-resource
+      function: schema
+      functionOptions:
+        schema:
+          type: object
+          required: [singular, plural, patterns, type]
+          properties:
+            type:
+              type: string
+              pattern: '^[a-z][a-z0-9./-]*/[a-z][a-z0-9-]*$'
+            singular:
+              type: string
+              pattern: '^[a-z][a-z0-9-]*$'
+            plural:
+              type: string
+              pattern: '^[a-z][a-z0-9-]*$'
+            patterns:
+              type: array
+              minItems: 1
+              items:
+                type: string
+                pattern: '^[a-z][a-z0-9-]*(/([a-z][a-z0-9-]*|\{[a-z][a-z0-9_]*\}))*$'
+            parents:
+              type: array
+              items:
+                type: string
+                pattern: '^[a-z][a-z0-9-]*$'
+            singleton:
+              type: boolean
+          additionalProperties: false

package/aep/0122.yaml

@@ -0,0 +1,110 @@
+aliases:
+  AepResource:
+    description: A schema that represents an AEP resource
+    targets:
+      - formats: ['oas2', 'oas3']
+        given:
+          - $.components.schemas[?(@['x-aep-resource'])]
+          - $.definitions[?(@['x-aep-resource'])]
+
+rules:
+  aep-122-resource-path-field:
+    description: Resources must have a 'path' field of type string.
+    message: Resource schema must include a 'path' property of type 'string'
+    severity: error
+    formats: ['oas2', 'oas3']
+    given: '#AepResource'
+    then:
+      function: schema
+      functionOptions:
+        schema:
+          type: object
+          properties:
+            properties:
+              type: object
+              properties:
+                path:
+                  type: object
+                  properties:
+                    type:
+                      const: string
+                  required: ['type']
+              required: ['path']
+          required: ['properties']
+
+  aep-122-collection-identifier-format:
+    description:
+      Collection identifiers must begin with a lowercase letter and contain only lowercase letters, numbers, and
+      hyphens.
+    message: Collection identifiers must match the pattern /[a-z][a-z0-9-]*/
+    severity: error
+    formats: ['oas2', 'oas3']
+    given: $.paths.*~
+    then:
+      function: pattern
+      functionOptions:
+        # Ensure collection segments start with lowercase letter
+        # and only contain lowercase letters, numbers, and hyphens
+        # Allow optional custom method suffix (e.g., :archive) without validating its format
+        match: '^(/[a-z][a-z0-9-]*(/\{[^}]+\})?)+(:[^/]*)?$'
+
+  aep-122-parent-field-type:
+    description: Parent fields in request parameters must be of type string.
+    message: The 'parent' parameter must be of type 'string'
+    severity: error
+    formats: ['oas2', 'oas3']
+    given:
+      - $.paths.*.*.parameters[?(@.name == 'parent')]
+      - $.paths.*.parameters[?(@.name == 'parent')]
+      - $.components.parameters[?(@.name == 'parent')]
+    then:
+      function: schema
+      functionOptions:
+        schema:
+          type: object
+          properties:
+            schema:
+              type: object
+              properties:
+                type:
+                  const: string
+              required: ['type']
+
+  aep-122-resource-id-type:
+    description: All resource ID fields must be of type string.
+    message: Resource ID fields (ending in '_id' or named 'id') must be of type 'string'
+    severity: error
+    formats: ['oas2', 'oas3']
+    given:
+      - "#AepResource.properties[?(@property.match(/_id$/) || @property == 'id')]"
+    then:
+      function: schema
+      functionOptions:
+        schema:
+          type: object
+          properties:
+            type:
+              const: string
+
+  aep-122-no-path-suffix:
+    description: Field names should not use the '_path' suffix unless necessary for disambiguation.
+    message:
+      "Avoid using '_path' suffix in field names; use the field name directly (e.g., 'book' instead of 'book_path')"
+    severity: warn
+    formats: ['oas2', 'oas3']
+    given:
+      - '#AepResource.properties.*~'
+    then:
+      function: pattern
+      functionOptions:
+        notMatch: '_path$'
+
+  aep-122-no-self-links:
+    description: Resources must not have a 'self_link' field.
+    message: Resources must not contain a 'self_link' field; use 'path' instead
+    severity: error
+    formats: ['oas2', 'oas3']
+    given:
+      - '#AepResource.properties.self_link'
+    then:
+      function: falsy

package/aep/0131.yaml

@@ -0,0 +1,78 @@
+aliases:
+  GetOperation:
+    description: A Get operation is a get 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(/\}$/))].get
+
+rules:
+  aep-131-operation-id:
+    description: The operation ID should be Get{resource-singular}.
+    message: The operation ID does not conform to AEP-131
+    severity: error
+    formats: ['oas2', 'oas3']
+    given: '#GetOperation'
+    then:
+      function: schema
+      functionOptions:
+        schema:
+          type: object
+          properties:
+            operationId:
+              type: string
+              pattern: '^[Gg][Ee][Tt][A-Z].*$'
+          required: ['operationId']
+
+  aep-131-request-body:
+    description: A get operation must not accept a request body.
+    severity: error
+    formats: ['oas3']
+    given:
+      - '#GetOperation.requestBody'
+    then:
+      function: falsy
+
+  aep-131-required-params:
+    description: A standard Get method must not have any required parameters other than path parameters.
+    severity: error
+    formats: ['oas2', 'oas3']
+    given:
+      - '#GetOperation.parameters[?(@.in != "path")]'
+      - '#GetOperation^.parameters[?(@.in != "path")]' # parameters at path item level
+    then:
+      field: required
+      function: falsy
+
+  aep-131-response-body:
+    description: The response must be the AEP resource.
+    message: The response body is not an AEP resource.
+    severity: error
+    formats: ['oas3']
+    given: '#GetOperation.responses.200.content[*].schema'
+    then:
+      function: schema
+      functionOptions:
+        schema:
+          type: object
+          required: ['x-aep-resource']
+
+  aep-131-unknown-optional-params:
+    description: A standard Get method should not have unknown optional parameters.
+    severity: warn
+    formats: ['oas2', 'oas3']
+    given:
+      - '#GetOperation.parameters[?(@.in == "query")]' # only check query parameters
+      - '#GetOperation^.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:
+              enum:
+                - 'read_mask' # AEP-157 Partial responses
+                - 'view' # AEP-157 Partial responses

package/aep/0132.yaml

@@ -0,0 +1,115 @@
+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-132-http-body:
+    description: A list operation must not accept a request body.
+    severity: error
+    formats: ['oas3']
+    given:
+      - '#ListOperation.requestBody'
+    then:
+      function: falsy
+
+  aep-132-operation-id:
+    description: The operation ID should be List{resource-singular}.
+    message: The operation ID does not conform to AEP-132
+    severity: error
+    formats: ['oas2', 'oas3']
+    given: '#ListOperation'
+    then:
+      function: skipSingletonsSchema
+      functionOptions:
+        schema:
+          type: object
+          properties:
+            operationId:
+              type: string
+              pattern: '^[Ll][Ii][Ss][Tt][A-Z].*$'
+          required: ['operationId']
+
+  aep-132-param-types:
+    description: List operation must use the correct type for any optional parameters.
+    severity: error
+    formats: ['oas3']
+    given:
+      - '#ListOperation.parameters'
+    then:
+      function: schema
+      functionOptions:
+        schema:
+          type: array
+          items:
+            oneOf:
+              - type: object
+                properties:
+                  name:
+                    type: string
+                    enum: ['filter']
+                  in:
+                    type: string
+                    enum: ['query']
+                  schema:
+                    type: object
+                    properties:
+                      type:
+                        type: string
+                        enum: ['string']
+                required: ['name']
+              - type: object
+                properties:
+                  name:
+                    type: string
+                    enum: ['order_by']
+                  in:
+                    type: string
+                    enum: ['query']
+                  schema:
+                    type: object
+                    properties:
+                      type:
+                        type: string
+                        enum: ['string']
+                required: ['name']
+              - type: object
+                properties:
+                  name:
+                    type: string
+                    enum: ['show_deleted']
+                  in:
+                    type: string
+                    enum: ['query']
+                  schema:
+                    type: object
+                    properties:
+                      type:
+                        type: string
+                        enum: ['boolean']
+                    required: ['name']
+              - type: object
+                properties:
+                  name:
+                    type: string
+                    not:
+                      enum: ['filter', 'order_by', 'show_deleted']
+                required: ['name']
+
+  aep-132-required-params:
+    description: List operation should have no required parameters (except path parameters)
+    severity: error
+    formats: ['oas3']
+    given:
+      - '#ListOperation.parameters[?(@.in != "path")]'
+    then:
+      field: required
+      function: falsy

package/aep/0133.yaml

@@ -0,0 +1,165 @@
+aliases:
+  CreateOperation:
+    description: A create operation is a post on path without a ":" in the final segment
+    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(/\}$/))].post
+
+rules:
+  aep-133-id-parameter:
+    description: A create operation should have an id parameter.
+    message: The id parameter is missing.
+    severity: warn
+    formats: ['oas2', 'oas3']
+    given:
+      - '#CreateOperation'
+    then:
+      function: schema
+      functionOptions:
+        schema:
+          type: object
+          required: ['parameters']
+          properties:
+            parameters:
+              type: array
+              contains:
+                type: object
+                required: ['name']
+                properties:
+                  name:
+                    enum: ['id']
+
+  aep-133-operation-id:
+    description: The operation ID should be Create{resource-singular}.
+    message: The operation ID does not conform to AEP-133.
+    severity: error
+    formats: ['oas2', 'oas3']
+    given: '#CreateOperation'
+    then:
+      function: schema
+      functionOptions:
+        schema:
+          type: object
+          properties:
+            operationId:
+              type: string
+              pattern: '^[Cc][Rr][Ee][Aa][Tt][Ee][A-Z].*$'
+          required: ['operationId']
+
+  aep-133-param-types:
+    description: The id parameter should be a query parameter of type string.
+    severity: error
+    formats: ['oas2', 'oas3']
+    given:
+      - '#CreateOperation.parameters[?(@.name == "id")]'
+    then:
+      function: schema
+      functionOptions:
+        schema:
+          type: object
+          required: ['in', 'schema']
+          properties:
+            in:
+              enum: ['query']
+            schema:
+              type: object
+              required: ['type']
+              properties:
+                type:
+                  type: string
+                  enum: ['string']
+
+  aep-133-request-body:
+    description: A standard create method must accept the resource in the request body.
+    message: The request body is not an AEP resource.
+    severity: error
+    formats: ['oas3']
+    given: '#CreateOperation'
+    then:
+      function: schema
+      functionOptions:
+        schema:
+          type: object
+          required: ['requestBody']
+          properties:
+            requestBody:
+              type: object
+              required: ['content']
+              properties:
+                content:
+                  type: object
+                  additionalProperties:
+                    type: object
+                    required: ['schema']
+                    properties:
+                      schema:
+                        type: object
+                        required: ['x-aep-resource']
+
+  aep-133-required-params:
+    description: A create operation must not have any required parameters other than path parameters.
+    severity: error
+    formats: ['oas2', 'oas3']
+    given:
+      - '#CreateOperation.parameters[?(@.in != "path")]'
+      - '#CreateOperation^.parameters[?(@.in != "path")]' # parameters at path item level
+    then:
+      field: required
+      function: falsy
+
+  aep-133-response-body:
+    description: The success response for a create operation must be the created AEP resource.
+    message: The response body is not an AEP resource.
+    severity: error
+    formats: ['oas3']
+    given: '#CreateOperation'
+    then:
+      function: schema
+      functionOptions:
+        schema:
+          type: object
+          required: ['responses']
+          properties:
+            responses:
+              type: object
+              anyOf:
+                - required: ['200']
+                - required: ['201']
+              properties:
+                '200':
+                  $ref: '#/definitions/response'
+                '201':
+                  $ref: '#/definitions/response'
+          definitions:
+            response:
+              type: object
+              required: ['content']
+              properties:
+                content:
+                  type: object
+                  additionalProperties:
+                    type: object
+                    required: ['schema']
+                    properties:
+                      schema:
+                        type: object
+                        required: ['x-aep-resource']
+
+  aep-133-unknown-optional-params:
+    description: A create operation should not have unknown optional parameters.
+    severity: warn
+    formats: ['oas2', 'oas3']
+    given:
+      - '#CreateOperation.parameters[?(@.in == "query")]' # only check query parameters
+      - '#CreateOperation^.parameters[?(@.in == "query")]' # parameters at path item level
+    then:
+      function: schema
+      functionOptions:
+        schema:
+          type: object
+          properties:
+            name:
+              type: string
+              enum: ['id']