sps-api-standards.spectral.yml

rules:
  sps-no-http-basic:
    description: "Consider a more secure alternative to HTTP Basic."
    message: "HTTP Basic is an insecure way to pass credentials around, use an alternative."
    severity: error
    given: $.components.securitySchemes[*]
    then:
      field: scheme
      function: pattern
      functionOptions:
        notMatch: basic
  ##### General #####
  # See https://atlassian.spscommerce.com/browse/DPE-286 
  # sps-no-collection-paging-capability:
  #   description: "Response bodies from collection endpoints SHOULD offer paging capability."
  #   severity: warn
  #   given: $.paths[?(!@property.match(/.*\/\{[^}]+\}$/))].get.responses['200'].content.application/json.schema.properties
  #   then:
  #     - field: "paging"
  #       function: truthy
  #     - field: "paging.type"
  #       function: pattern
  #       functionOptions:
  #         match: "object"

  ##### Root Element #####
  sps-collection-missing-results-array:
    description: "Response bodies must have a root element called results and is an array of objects."
    severity: error
    given: $.paths[?(!@property.match(/.*\/\{[^}]+\}$/))].get.responses['200'].content.application/json.schema.properties.results
    then:
      - field: type
        function: pattern
        functionOptions:
          match: "array"
      - field: items.type
        function: pattern
        functionOptions:
          match: "object"
  ##### Pagination #####
  sps-missing-pagination-query-parameters:
    description: "Collection GET endpoints SHOULD support pagination using query parameters. Offset or cursor based pagination is required."
    severity: warn
    given: $.paths[?(!@property.match(/.*\/\{[^}]+\}\/*.*/))].get
    then:
      - field: parameters
        function: schema
        functionOptions:
          schema:
            type: array
            items:
              type: object
            contains:
              type: object
              properties:
                name:
                  const: limit
                in:
                  const: query
            allOf:
              - anyOf:
                  - contains:
                      type: object
                      properties:
                        name:
                          const: offset
                        in:
                          const: query
                  - contains:
                      type: object
                      properties:
                        name:
                          const: cursor
                        in:
                          const: query
  sps-post-request-body-missing-paging-object:
    description: "POST collection endpoints MUST have a request body schema that includes paging parameters."
    severity: error
    given: $.paths[?(!@property.match(/.*\/\{[^}]+\}$/))].post.requestBody.content.application/json.schema.properties.paging
    then:
      field: "type"
      function: pattern
      functionOptions:
        match: "object"
  ##### FILTERING #####
  sps-disallow-resource-identifier-filtering:
    description: "Resource identifier filtering is not allowed as a query parameter. Use the resource identifier in the URL path."
    severity: warn
    given: $.paths..get.parameters.[?(@.in=='query' && @.name=='id')]
    then:
      field: "name"
      function: pattern
      functionOptions:
        notMatch: "^id$"
  sps-filtering-only-get-requests:
    description: "Only GET-based endpoints SHOULD have have the query parameter 'filter'."
    severity: error
    given: $.paths.*[?(@property!='get')].parameters.[?(@.in=='query' && @.name=='filter')].name
    then:
      function: falsy
      # Commented out because 
      # https://github.com/SPSCommerce/sps-api-standards/pull/86#discussion_r1680361945
  # sps-unreasonable-query-parameters-limit:
  #   description: "Filtering query parameters SHOULD have a reasonable limit, no more than 12."
  #   severity: warn
  #   given: $.paths..get
  #   then:
  #     function: schema
  #     functionOptions:
  #       schema:
  #         type: object
  #         properties:
  #           parameters:
  #             type: array
  #             minContains: 0
  #             maxContains: 12
  #             contains:
  #               type: object
  #               properties:
  #                 in:
  #                   const: query
  sps-hybird-filtering-exists-with-root-filter:
    description: "Hybrid filtering MAY be offered on multiple attributes, but MUST never exist if a root \"filter\" query parameter is present."
    severity: error
    given: $.paths..get.parameters^
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          properties:
            parameters:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                  in:
                    type: string
          allOf:
            - if:
                properties:
                  parameters:
                    type: array
                    contains:
                      type: object
                      properties:
                        name:
                          const: filter
              then:
                not:
                  properties:
                    parameters:
                      type: array
                      contains:
                        type: object
                        properties:
                          name:
                            type: string
                            pattern: \w+Filter
  ##### SORTING #####
  sps-sorting-parameters-only-get-requests:
    description: "Non-GET endpoints MUST NOT have sorting query parameters. Parameter names such as sort, sorting, orderBy, etc."
    severity: error
    given: $.paths.*[?(@property!='get')].parameters.[?(@.in=='query')]
    then:
      field: "name"
      function: pattern
      functionOptions:
        notMatch: "^sort|sorting|sortBy|order|ordering|orderBy$"
  sps-unknown-error-format:
    description: "Every error response SHOULD support RFC 7807."
    severity: error
    given: $.paths...responses[?(@property.match(/^(4|5)/))].content.*~
    then:
      function: enumeration
      functionOptions:
        values:
          - application/problem+xml
          - application/problem+json
  ##### General #####
  sps-no-keyword-conflicts:
    description: Names that may conflict with keywords in common programming languages SHOULD NOT be used.
    severity: warn
    given: "$..properties.*~"
    then:
      function: pattern
      functionOptions:
        notMatch: ^(abstract|for|new|switch|assert|default|goto|package|synchronized|boolean|do|if|private|this|break|double|implements|throw|byte|else|import|public|throws|case|enum|instanceof|return|transient|catch|extends|int|short|try|char|final|interface|static|void|class|finally|long|volatile|const|float|native|super|while)$
  ##### Property Names #####
  sps-camel-case-properties:
    description: Property names and acronyms MUST be in camelCase.
    severity: error
    formats: [oas3]
    given: "$..properties.*~"
    then:
      function: pattern
      functionOptions:
        match: ^[a-z][a-z0-9]*(([A-Z]{2}|[A-Z])[a-z0-9]+)*$
  sps-disallowed-prepositions:
    description: Property names SHOULD NOT include prepositions (e.g. "for", "during", "at", etc.)
    severity: warn
    formats: [oas3]
    given: "$..properties.*~"
    then:
      function: pattern
      functionOptions:
        notMatch: (^(about|above|across|after|against|among|around|at|before|behind|below|beside|between|down|during|for|from|in|inside|into|near|of|off|on|out|over|through|to|toward|under|up|with|as|but|like|since|than|till|unlike|until|upon|within|without)([A-Z]|$)|.*(About|Above|Across|After|Against|Among|Around|At|Before|Behind|Below|Beside|Between|Down|During|For|From|In|Inside|Into|Near|Of|Off|On|Out|Over|Through|To|Toward|Under|Up|With|As|But|Like|Since|Than|Till|Unlike|Until|Upon|Within|Without)([A-Z]|$)).*
  sps-disallowed-boolean-prefixes:
    description: Boolean properties SHOULD NOT use is, has, or another prefix.
    severity: warn
    formats: [oas3]
    given: "$..properties[?(@ && @.type == 'boolean')]~"
    then:
      function: pattern
      functionOptions:
        notMatch: "^(is|has|was|will|needs|uses|should|can)([A-Z]|$).*"
  ##### Domain References #####
  sps-ref-property-name:
    description: Property with the name 'ref' MUST be of type 'sps-ref' following URN-like reference formats.
    severity: error
    formats: [oas3]
    given: '$..properties..[?((@property=== "ref" || @property === "Ref") && @.$ref == null && @.allOf == null && @.oneOf == null && @.type != null)]'
    resolved: false
    then:
      - field: "format"
        function: truthy
      - field: "format"
        function: pattern
        functionOptions:
          match: "sps-ref"
  sps-ref-schema:
    description: Properties following 'sps-ref' format MUST use the standardized schema - maxLength (255), minLength(7), pattern (includes 'sps'), type (string).
    message: "{{property}} is not provided or not following required schema values."
    severity: error
    formats: [oas3]
    given: '$..[?(@property=== "format" && @ == "sps-ref")]^'
    then:
      - function: schema
        functionOptions:
          schema:
            type: object
            required:
              - maxLength
              - minLength
              - type
              - pattern
            properties:
              maxLength:
                type: integer
                minimum: 255
                maximum: 255
              minLength:
                type: integer
                minimum: 7
                maximum: 7
              type:
                type: string
              pattern:
                type: string
      - field: pattern
        function: pattern
        functionOptions:
          match: "sps"
      - field: type
        function: pattern
        functionOptions:
          match: "^string$"
  ##### Standard Properties #####
  sps-invalid-id-type:
    description: id SHOULD use a data type of 'string'.
    severity: warn
    formats: [oas3]
    given: '$..[?(@property === "id")].type'
    then:
      function: pattern
      functionOptions:
        match: "^string$"
  sps-mandate-abbreviations-identifier:
    description: Use abbreviations instead of long form names, i.e. identifier SHOULD BE id.
    severity: warn
    formats: [oas3]
    given: '$..properties.*~'
    then:
      function: pattern
      functionOptions:
        notMatch: "^identifier$"
  sps-mandate-abbreviations-organization:
    description: Use abbreviations instead of long form names, i.e. organization SHOULD BE org.
    severity: warn
    formats: [oas3]
    given: '$..properties.*~'
    then:
      function: pattern
      functionOptions:
        notMatch: "(^organization([A-Z]|$)|Organization([A-Z]|$))"
  sps-invalid-ref-type:
    description: ref MUST use a data type of 'string'.
    severity: error
    formats: [oas3]
    given: '$..[?(@property === "ref")].type'
    then:
      function: pattern
      functionOptions:
        match: "^string$"
  sps-invalid-orgid-type:
    description: orgId MUST use a data type of 'string'.
    severity: error
    formats: [oas3]
    given: '$..[?(@property === "orgId")].type'
    then:
      function: pattern
      functionOptions:
        match: "^string$"
  sps-invalid-name-type:
    description: name MUST use a data type of 'string'.
    severity: error
    formats: [oas3]
    given: '$..[?(@property === "name")].type'
    then:
      function: pattern
      functionOptions:
        match: "^string$"
  sps-invalid-description-type:
    description: description MUST use a data type of 'string'.
    severity: error
    formats: [oas3]
    given: '$..[?(@property === "description")].type'
    then:
      function: pattern
      functionOptions:
        match: "^string$"
  sps-invalid-request-id-type:
    description: requestId MUST use a data type of 'string'.
    severity: error
    formats: [oas3]
    given: '$..[?(@property === "requestId")].type'
    then:
      function: pattern
      functionOptions:
        match: "^string$"
  sps-invalid-created-date-time-type:
    description: createdDateTime MUST use a data type of 'string' with the format 'date-time'.
    severity: error
    formats: [oas3]
    given: "$..properties.createdDateTime"
    then:
      - field: type
        function: pattern
        functionOptions:
          match: "^string$"
      - field: format
        function: truthy
      - field: format
        function: pattern
        functionOptions:
          match: "^date-time$"
  sps-invalid-created-by-type:
    description: createdBy MUST use a data type of 'string'.
    severity: error
    formats: [oas3]
    given: '$..[?(@property === "createdBy")].type'
    then:
      function: pattern
      functionOptions:
        match: "^string$"
  sps-invalid-modified-date-time-type:
    description: modifiedDateTime MUST use a data type of 'string' with the format 'date-time'.
    severity: error
    formats: [oas3]
    given: "$..properties.modifiedDateTime"
    then:
      - field: type
        function: pattern
        functionOptions:
          match: "^string$"
      - field: format
        function: truthy
      - field: format
        function: pattern
        functionOptions:
          match: "^date-time$"
  sps-invalid-modified-by-type:
    description: modifiedBy MUST use a data type of 'string'.
    severity: error
    formats: [oas3]
    given: '$..[?(@property === "modifiedBy")].type'
    then:
      function: pattern
      functionOptions:
        match: "^string$"
  sps-invalid-deleted-by-type:
    description: deletedBy MUST use a data type of 'string'.
    severity: error
    formats: [oas3]
    given: '$..[?(@property === "deletedBy")].type'
    then:
      function: pattern
      functionOptions:
        match: "^string$"
  sps-invalid-fingerprint-type:
    description: Fingerprint values MUST use a data type of `string`.
    severity: error
    formats: [oas3]
    given: '$..[?(@property === "fingerprint")].type'
    then:
      function: pattern
      functionOptions:
        match: "^string$"
  sps-fingerprint-naming:
    description: Rather than property names refering to the implementation for 'hash' or 'hashkey', you MUST use the property name 'fingerprint'.
    message: "{{property}} is not using property name fingerprint."
    severity: error
    formats: [oas3]
    given: "$.components.schemas..properties.*~"
    then:
      function: pattern
      functionOptions:
        notMatch: "^hashkey|hashKey|hash$"
  ##### General #####
  sps-invalid-response-body:
    description: Response bodies must be an object type.
    severity: error
    given: $.paths[*][*].responses[*].content.application/json.schema.type
    then:
      function: pattern
      functionOptions:
        match: "object"
  ##### HTTP Status Codes #####
  sps-invalid-status-code:
    description: An API MUST return HTTP response codes in conformance with RFC-2616 and common usage.
    severity: error
    given: $.paths...responses.*~
    then:
      function: enumeration
      functionOptions:
        values: ["200", "201", "202", "204", "400", "401", "403", "404", "405", "406", "409", "412", "415", "428", "429", "500"]
  sps-missing-500-response:
    description: Every endpoint SHOULD have a 500 response
    severity: warn
    given: "$.paths[*][*]"
    then:
      field: responses.500
      function: truthy
  ##### HTTP Headers #####
  sps-headers-hyphenated-pascal-case:
    description: All `HTTP` headers MUST use `Hyphenated-Pascal-Case` notation
    severity: error
    given: "$..parameters[?(@.in == 'header')].name"
    type: style
    then:
      function: pattern
      functionOptions:
        match: "/^([A-Z][a-z0-9]-)*([A-Z][a-z0-9])+/"
  sps-no-x-headers:
    description: "Do not use headers with X-"
    severity: warn
    message: "Headers cannot start with X-. More: https://tools.ietf.org/html/rfc6648"
    given: "$..parameters.[?(@.in === 'header')].name"
    then:
      function: pattern
      functionOptions:
        notMatch: "^(x|X)-"
  sps-no-x-response-headers:
    description: "Do not use headers with X-"
    severity: warn
    message: "Headers cannot start with X-, so please find a new name for {{property}}. More: https://tools.ietf.org/html/rfc6648"
    given: "$..headers.*~"
    then:
      function: pattern
      functionOptions:
        notMatch: "^(x|X)-"
  sps-invalid-location-header:
    description: Location header MUST NOT be present in non-201 responses
    severity: error
    given: $.paths[*][*].responses[?(@property !== '201')].headers
    then:
      field: Location
      function: falsy
  sps-authorization-missing:
    description: Security field MUST be present at the root of the spec with at least one item (ie. HTTPBearer, Token, APIKey, etc.)
    severity: error
    given: "$"
    then:
      field: "security"
      function: schema
      functionOptions:
        schema:
          type: array
          minItems: 1
  sps-default-content-language:
    description: Content-Language is optional but MUST default locale to en-US when none provided
    severity: error
    given: $.paths[*][*].responses[*].headers.Content-Language.schema.default
    then:
      function: pattern
      functionOptions:
        match: "en-US"
  sps-no-explicit-headers:
    description: Access-Control-*, Content-Type, and Accept Headers SHOULD NOT be specified explicitly in a spec as it an operational concern.
    severity: warn
    given: "$.paths[*][*].responses[*].headers"
    then:
      function: pattern
      functionOptions:
        notMatch: "^(Access-Control-.*|Content-Type|Accept)$"
  sps-invalid-custom-header-format:
    description: Custom headers MUST NOT be longer than 50 chars, and MUST only contain alphanumeric and dash chars, and MUST begin with SPS- not x-
    severity: error
    given: "$.paths[*][*].responses[*].headers.*~"
    then:
      function: pattern
      functionOptions:
        match: "^(Sps-[a-zA-Z0-9-]{1,50}|Accept|Access-Control.*|Authorization|Cache-Control|Content-Language|Content-Length|Content-Type|Date|ETag|Host|If-Match|If-None-Match|Location|Origin|User-Agent)$"
  sps-sensitive-data-in-headers:
    description: Headers MUST NOT contain sensitive data.
    severity: error
    given: "$.paths[*][*].responses[*].headers.*~"
    then:
      function: pattern
      functionOptions:
        notMatch: "^(SPS-Token|SPS-Password|SPS-Identity|Password)$"
  ##### MIME Types #####
  sps-no-resource-extensions:
    description: Request and Response media type formats MUST NOT be implied using extensions on resources (i.e. .json or .xml). Instead, use the standard resource path with the appropriate Content-Type header
    severity: error
    given: "$.paths.*~"
    then:
      function: pattern
      functionOptions:
        notMatch: "\\.json|\\.xml|\\.yml|\\.yaml"
  sps-invalid-mime-type:
    description: MIME types MUST be standard (application/json, application/problem+json, application/problem+xml) or use custom format application/vnd.*
    severity: error
    given: $.paths[*][*].responses[*].content.*~
    then:
      function: pattern
      functionOptions:
        match: "^application/(json|problem\\+json|problem\\+xml|vnd\\..*)$"
  ##### HTTP Methods #####
  sps-invalid-http-method:
    description: Operations MUST use only the common HTTP methods as outlined in the standards guide, and must be in lower-case
    severity: error
    given: $.paths[*].*~
    then:
      field: "method"
      function: enumeration
      functionOptions:
        values: ["get", "post", "put", "patch", "delete", "head", "options"]
  sps-request-get-invalid-body:
    description: A `GET` request MUST NOT accept a request body
    severity: error
    given: $.paths[*][get].requestBody
    then:
      function: undefined
  sps-response-get-missing-body:
    description: A `GET` operation must return a response body
    severity: error
    given: $.paths[*].get.responses[*]
    then:
      field: "content"
      function: "truthy"
  sps-invalid-get-response-code:
    description: GET operations should not use status codes 201, 202, 204, 409, 412
    severity: warn
    given: $.paths[*].get.responses
    then:
      field: "@key"
      function: "pattern"
      functionOptions:
        notMatch: "^(201|202|204|409|412)$"
  sps-response-get-missing-success-code:
    description: GET operations must always return 200 status code
    severity: error
    given: $.paths[*].get.responses
    then:
      - field: "200"
        function: truthy
  sps-invalid-post-response-code:
    description: POST operations should not return 412 status codes
    given: $.paths[*].post.responses
    severity: warn
    then:
      field: "@key"
      function: pattern
      functionOptions:
        notMatch: "412"
  sps-invalid-put-response-code:
    description: PUT operations should not return 200 or 201 status codes
    severity: warn
    given: $.paths[*].put.responses
    then:
      field: "@key"
      function: pattern
      functionOptions:
        notMatch: "^(200|201)$"
  sps-invalid-delete-response-code:
    description: DELETE operations should not return 200 or 201 status codes
    severity: warn
    given: $.paths[*].delete.responses
    then:
      field: "@key"
      function: pattern
      functionOptions:
        notMatch: "^(200|201)$"
  sps-request-delete-invalid-body:
    description: DELETE operations must not accept a request body
    severity: error
    given: $.paths[*].delete.requestBody
    then:
      function: undefined
  sps-response-delete-invalid-body:
    description: DELETE operations must not have a response body
    severity: error
    given: $.paths.*.delete.responses[202,204].content
    then:
      function: falsy
  sps-invalid-patch-response-code:
    description: PATCH operations should not return 201 status code
    severity: warn
    given: $.paths[*].patch.responses
    then:
      field: "@key"
      function: pattern
      functionOptions:
        notMatch: "^201$"
  sps-request-patch-missing-body:
    description: PATCH operations must have a request body
    severity: error
    given: $.paths[*].patch
    then:
      field: requestBody
      function: schema
      functionOptions:
        schema:
          type: object
  sps-invalid-head-response-code:
    description: HEAD operations should not return 201, 202, 204, 409, 412 status codes
    severity: warn
    given: $.paths[*].head.responses
    then:
      field: "@key"
      function: pattern
      functionOptions:
        notMatch: "^(201|202|204|409|412)$"
  sps-request-head-invalid-body:
    description: A `HEAD` request MUST NOT accept a request body
    severity: error
    given: $.paths[*][head].requestBody
    then:
      function: undefined
  sps-response-head-invalid-body:
    description: HEAD operations should not return a response body for success
    given: $.paths.*.head.responses[200].content
    severity: error
    then:
      function: falsy
  sps-invalid-options-response-code:
    description: OPTIONS operations should not return 201, 202, 409, 412 status codes
    severity: warn
    given: $.paths[*].options.responses
    then:
      field: "@key"
      function: pattern
      functionOptions:
        notMatch: "^(201|202|409|412)$"
  sps-request-options-invalid-body:
    description: An `OPTIONS` request MUST NOT accept a request body
    severity: error
    given: $.paths[*][options].requestBody
    then:
      function: undefined
  sps-response-options-invalid-body:
    description: OPTIONS operations should not return a response body for success
    given: $.paths.*.options.responses[200, 204].content
    severity: error
    then:
      function: falsy
  # ignoring contact information as that is typically handled at a higher level of concern than each API spec individually
  info-contact: off
  # operation ids are essential for changelogs and other evolutions over time
  operation-operationId: error
  operation-operationId-unique: error
  # buggy with examples, problem in spectral: https://github.com/stoplightio/spectral/issues/2081
  oas3-valid-media-example: off
  sps-request-support-json:
    description: Every request MUST support `application/json` media type
    formats: [oas3]
    severity: error
    given: $.paths[*][*].requestBody.content
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          properties:
            application/json: true
          required:
            - application/json
  sps-no-numeric-ids:
    description: Avoid exposing IDs as an integer, UUIDs or other interoperable strings are preferred.
    severity: warn
    given: $.paths..parameters[*].[?(@property === "name" && (@ === "id" || @ === "ID" || @ === "Id"))]^.schema
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          not:
            properties:
              type:
                const: integer
          properties:
            format:
              const: uuid
  sps-semver:
    severity: warn
    message: Version should use semantic versioning. {{value}} is not a valid version.
    given: $.info.version
    then:
      function: pattern
      functionOptions:
        match: "^([0-9]+.[0-9]+.[0-9]+)$"
  sps-schema-names-pascal-case:
    severity: warn
    description: Schema names SHOULD be written in PascalCase
    message: '{{property}} is not PascalCase: {{error}}'
    recommended: true
    type: style
    given: '$.components.schemas.*~'
    then:
      function: pattern
      functionOptions:
        match: '^[A-Z][a-zA-Z0-9]*$'
  sps-response-names-pascal-case:
    severity: warn
    description: Response names SHOULD be written in PascalCase
    message: '{{property}} is not PascalCase: {{error}}'
    recommended: true
    type: style
    given: '$.components.responses.*~'
    then:
      function: pattern
      functionOptions:
        match: '^[A-Z][a-zA-Z0-9]*$'
  sps-limit-path-size:
    message: APIs SHOULD NOT expand their total URL length beyond a few hundred characters.
    severity: warn
    given: $.paths.*~
    then:
      function: length
      functionOptions:
        max: 100
  sps-hosts-https-only:
    message: "Servers MUST be https and no other protocol is allowed unless using localhost."
    formats: [oas3]
    severity: error
    given: $.servers..url
    then:
      function: pattern
      functionOptions:
        match: ^(https:|http://localhost)
  sps-hosts-lowercase:
    message: "Server URL SHOULD BE lowercase."
    formats: [oas3]
    severity: warn
    given: $.servers..url
    then:
      function: pattern
      functionOptions:
        match: ^[^A-Z]*$
  sps-hosts-spscommerce-domain:
    message: "APIs SHOULD be accessible under api.spscommerce.com."
    formats: [oas3]
    severity: warn
    given: $.servers..url
    then:
      function: pattern
      functionOptions:
        match: api.spscommerce.com|api.sps-internal.com|localhost
  sps-path-no-environment:
    message: "API paths MUST NOT indicate environment names."
    severity: error
    given: $.paths.*~
    then:
      function: pattern
      functionOptions:
        notMatch: /prod/|/preprod/|/dev/|/test/|/integration/|/stage/
  sps-hosts-no-port:
    message: "Port MUST NOT be specified or required to use the API, except for 'localhost' testing in a spec."
    formats: [oas3]
    severity: error
    given: $.servers..url
    then:
      function: pattern
      functionOptions:
        notMatch: (?!https?://localhost)(https?://.*):(\d*)\/?(.*)
  sps-paths-expose-technology:
    message: "A resource MUST NOT leak or expose format or technology-specific information at any point in the path."
    severity: error
    given: $.paths.*~
    then:
      function: pattern
      functionOptions:
        notMatch: (.php|.asp|.jsp|.cgi|.psp|.json|.xml)
  sps-paths-expose-extension:
    message: "A resource SHOULD NOT make use of an extension at any point in the path."
    severity: warn
    given: $.paths.*~
    then:
      function: pattern
      functionOptions:
        notMatch: \.
  sps-paths-kebab-case:
    message: "A resource containing multiple words MUST be separated using kebab-case (lower case and separated with hyphens)."
    severity: error
    given: $.paths[?(/^((?!_webhooks).)*$/i.test(@property))]~
    then:
      function: pattern
      # (\/[a-z]+_.) looks for any instance of a forward slash followed by a lowercase character followed by an underscore
      # (\/([a-z]|[A-Z])+[A-Z])looks for any instance of a forward slash followed by a lowercase of uppercase character followed by an uppercase character
      functionOptions:
        notMatch: (\/[a-z]+_.)|(\/([a-z]|[A-Z])+[A-Z])
  # Performance issue with spectral-cli and the regex provided - https://github.com/SPSCommerce/sps-api-standards/issues/26
  # sps-paths-no-special-characters:
  #  message: "A resource MUST only contain lowercase ISO basic Latin alphabet characters, the numeric characters `0-9`, and a hyphen or dash character. Parameters must be camel cased."
  #  severity: error
  #  given: $.paths.*~
  #  then:
  #    function: pattern
  #    functionOptions:
  #      match: ^([0-9a-z-\/]*({[a-z][0-9a-zA-Z-]+})?)*$
  sps-paths-trailing-slash:
    message: "A resource MUST be addressable without a trailing slash on the path."
    severity: error
    given: $.paths.*~
    then:
      function: pattern
      functionOptions:
        notMatch: "/$"
  sps-paths-with-api:
    message: "A resource SHOULD NOT contain 'api' as a prefix in or a part of the path."
    severity: error
    given: $.paths.*~
    then:
      function: pattern
      functionOptions:
        notMatch: /api|/api/|-api/
  sps-paths-empty-segments:
    message: "A resource MUST use normalized paths without empty path segments."
    severity: error
    given: $.paths.*~
    then:
      function: pattern
      functionOptions:
        notMatch: //
  sps-paths-limit-path-parameters:
    message: The URL path should not contain more than 3 dynamic path parameters.
    severity: warn
    given: $.paths.*~
    then:
      function: pattern
      functionOptions:
        notMatch: ^(.*{{1}.*){4,}
  sps-paths-limit-sub-resources:
    message: The hierarchy of nested resources SHOULD NOT contain more than 8 resource names in the path.
    severity: warn
    given: $.paths.*~
    then:
      function: pattern
      functionOptions:
        notMatch: ^([^/]*/){9,}
  sps-paths-with-http-methods:
    message: "A resource SHOULD NOT contain HTTP methods."
    severity: error
    given: $.paths.*~
    then:
      function: pattern
      functionOptions:
        notMatch: (\/get|\/post|\/put|\/delete|\/patch)
  sps-paths-params-camel-case:
    message: "Path parameter keys MUST use camelCase."
    severity: error
    given: $.paths.*.*.parameters[?(@.in=='path')].name
    then:
      function: casing
      functionOptions:
        type: camel
        disallowDigits: true
  sps-query-params-characters:
    message: "Query parameter keys MUST include only alpha-numeric characters and periods: [Aa0-Zz9]'."
    severity: error
    given: $.paths.*.*.parameters[?(@.in=='query')].name
    then:
      function: pattern
      functionOptions:
        match: "^[A-Za-z0-9\\.]+$"
  sps-query-params-camel-case:
    message: "Query parameter keys MUST use camelCase."
    severity: error
    given: $.paths.*.*.parameters[?(@.in=='query')].name
    then:
      function: casing
      functionOptions:
        type: camel
        disallowDigits: true
        separator:
          char: .
          allowLeading: false
  sps-query-params-not-required:
    message: "Query parameters MUST be optional."
    severity: error
    given: $.paths.*.*.parameters[?(@.in=='query')].required
    then:
      function: falsy
  sps-query-params-no-api-keys:
    message: "Query parameters MUST not contain sensitive information, like API tokens or keys."
    severity: error
    given: $.paths.*.*.parameters[?(@.in=='query')].name
    then:
      function: pattern
      functionOptions:
        notMatch: "apiKey|token"
  sps-query-params-not-in-path:
    message: "Paths SHOULD NOT have query parameters in them. They should be defined separately in the OpenAPI."
    severity: warn
    given: $.paths.*~
    then:
      function: pattern
      functionOptions:
        notMatch: \?
  sps-webhooks-internal:
    description: "Webhooks MUST be marked as internal using 'x-internal: true'."
    formats: [oas3]
    severity: error
    given: $.paths[?(/^.*\/_webhooks\/.*$/i.test(@property))].*
    then:
      field: x-internal
      function: truthy
  sps-webhooks-post:
    description: Webhooks SHOULD be POST requests.
    formats: [oas3]
    severity: warn
    given: $.paths[?(/^.*\/_webhooks\/.*$/i.test(@property))].*~
    then:
      function: pattern
      functionOptions:
        match: "^post$"
  sps-webhooks-path:
    description: Webhook endpoints should be under the the path '/_webhooks/' to be identified as internal usage only.
    formats: [oas3]
    severity: error
    given: $.paths[?(/^.*webhook.*$/i.test(@property))]~
    then:
      function: pattern
      functionOptions:
        match: ^.*\/_webhooks\/.*$
documentationUrl: https://spscommerce.github.io/sps-api-standards
extends:
  - spectral:oas
# NOTE: this is copied to ".spectral.yml" as well for testing locally (this is the version that is deployed)
overrides:
  # disable linting validation for all webhooks, since we are at the mercy of the webhook provider
  # overrides do not inherit through "extends", so only directly using the SPS ruleset do these override apply
  # https://meta.stoplight.io/docs/spectral/branches/develop/293426e270fac-overrides
  - files:
      # NOTE: after paths, you cannot use "**" wildcard as a prefix... :(
      # But everything after is automatically a wildcard (just not before)
      - "**#/paths/~1_webhooks"
      - "**#/paths/~1v1~1_webhooks"
      - "**#/paths/~1v2~1_webhooks"
      - "**#/paths/~1v3~1_webhooks"
    rules:
      sps-request-support-json: off
      sps-schema-names-pascal-case: off
      sps-paths-params-camel-case: off
      sps-query-params-not-required: off
      sps-headers-hyphenated-pascal-case: off
      sps-no-x-headers: off
      sps-paths-kebab-case: off