Spotlight Rules API Rules

# Spotlight Rules — spotlight-recommended ruleset (verbatim)
# generated: 
# method: searched
# source: https://raw.githubusercontent.com/api-commons/spotlight-validator/main/rules/spotlight-recommended.yaml
# note: Published by the Spotlight Rules project (api-commons/spotlight-validator, CNAME
#   validator.spotlight-rules.com). Compiled by Spotlight from public Spectral rulesets;
#   each rule carries source:* / category:* / format:* tags for attribution. Body below is
#   byte-for-byte as served; only these comment lines were prepended.
description: Spotlight best-of-breed API governance ruleset, compiled from
  public Spectral rulesets. Select rules with tags (source:*, category:*,
  format:*).
documentationUrl: https://github.com/api-commons/spotlight-validator
extends:
  - - spotlight:oas
    - recommended
rules:
  path-segments-kebab-case:
    description: "All YAML/JSON paths MUST follow kebab-case. It requires the
      targeted value to match the pattern
      `^/([a-z0-9]+(-[a-z0-9]+)*)?(/[a-z0-9]+(-[a-z0-9]+)*|/{.+})*$` (evaluated
      at `$.paths[*]~`). Severity: warn."
    severity: warn
    recommended: true
    message: "{{property}} is not kebab-case: {{error}}"
    given: $.paths[*]~
    then:
      function: pattern
      functionOptions:
        match: ^/([a-z0-9]+(-[a-z0-9]+)*)?(/[a-z0-9]+(-[a-z0-9]+)*|/{.+})*$
    tags:
      - source:adidas
      - format:openapi
      - spec:paths
      - experience:naming
      - experience:consistency
  path-parameters-camel-case:
    description: "Path parameters MUST follow camelCase. It requires the targeted
      value to match the pattern `^[a-z][a-zA-Z0-9]+$` (evaluated at
      `$..parameters[?(@.in == 'path')].name`). Severity: warn."
    severity: warn
    recommended: true
    message: "{{property}} path parameter is not camelCase: {{error}}"
    given: $..parameters[?(@.in == 'path')].name
    then:
      function: pattern
      functionOptions:
        match: ^[a-z][a-zA-Z0-9]+$
    tags:
      - source:adidas
      - format:openapi
      - spec:parameters
      - experience:naming
      - experience:consistency
  schema-definitions-camel-case:
    description: "All YAML/JSON definitions MUST follow fields-camelCase and be
      ASCII alphanumeric characters or `_` or `$`. It requires the targeted
      value to match the pattern `/^[a-z$_]{1}[A-Z09$_]*/` (evaluated at
      `$.definitions[*]~`). Severity: error."
    severity: error
    recommended: true
    message: "{{property}} MUST follow camelCase and be ASCII alphanumeric
      characters or `_` or `$`."
    given: $.definitions[*]~
    then:
      function: pattern
      functionOptions:
        match: /^[a-z$_]{1}[A-Z09$_]*/
    tags:
      - source:adidas
      - format:openapi
      - spec:document
      - experience:naming
      - experience:consistency
  schema-properties-camel-case:
    description: "All JSON Schema properties MUST follow fields-camelCase and be
      ASCII alphanumeric characters or `_` or `$`. It requires the targeted
      value to match the pattern `/^[a-z$_]{1}[A-Z09$_]*/` (evaluated at
      `$.definitions..properties[*]~`). Severity: error."
    severity: error
    recommended: true
    message: "{{property}} MUST follow camelCase and be ASCII alphanumeric
      characters or `_` or `$`."
    given: $.definitions..properties[*]~
    then:
      function: pattern
      functionOptions:
        match: /^[a-z$_]{1}[A-Z09$_]*/
    tags:
      - source:adidas
      - format:openapi
      - spec:schemas
      - experience:naming
      - experience:consistency
  header-names-hyphenated-pascal-case:
    description: "All `HTTP` headers MUST use `Hyphenated-Pascal-Case` notation. It
      requires the targeted value to match the pattern
      `/^([A-Z][a-z0-9]-)*([A-Z][a-z0-9])+/` (evaluated at `$..parameters[?(@.in
      == 'header')].name`). Severity: error."
    severity: error
    given: $..parameters[?(@.in == 'header')].name
    message: "'HTTP' headers MUST follow 'Hyphenated-Pascal-Case' notation"
    recommended: true
    type: style
    then:
      function: pattern
      functionOptions:
        match: /^([A-Z][a-z0-9]-)*([A-Z][a-z0-9])+/
    tags:
      - source:adidas
      - format:openapi
      - spec:parameters
      - spec:headers
      - experience:naming
      - experience:consistency
      - source:sps-commerce
  request-support-json-media-type:
    description: "Every request MUST support `application/json` media type. It
      requires the targeted value to be absent or empty (evaluated at
      `$.paths.[*].requestBody.content[?(@property.indexOf('json') === -1)]^`).
      Severity: error."
    formats:
      - oas3
    recommended: true
    severity: error
    message: "{{description}}: {{error}}"
    given: $.paths.[*].requestBody.content[?(@property.indexOf('json') === -1)]^
    then:
      function: falsy
    tags:
      - source:adidas
      - format:openapi
      - spec:paths
      - spec:request-body
      - spec:media-types
      - experience:consistency
      - experience:usability
  require-https-servers:
    description: "ALL requests MUST go through `https` protocol only. It requires
      the targeted value to match the pattern `/^https:/` (evaluated at
      `$.servers..url`). Severity: error."
    formats:
      - oas3
    recommended: true
    severity: error
    message: Servers MUST be https and no other protocol is allowed.
    given: $.servers..url
    then:
      function: pattern
      functionOptions:
        match: /^https:/
    tags:
      - source:adidas
      - format:openapi
      - spec:servers
      - experience:security
  success-response-use-hal-json:
    description: 'All success responses MUST be of media type
      `application/hal+json`. It requires the targeted value to be one of
      ["application/hal+json"] (evaluated at `$.paths..responses[?( @property >=
      201 && @property < 300 && @property != 204)].content[*]~`). Severity:
      error.'
    severity: error
    given: $.paths..responses[?( @property >= 201 && @property < 300 && @property !=
      204)].content[*]~
    recommended: true
    formats:
      - oas3
    message: "Response documents MUST be of application/hal+json media types: {{error}}"
    then:
      function: enumeration
      functionOptions:
        values:
          - application/hal+json
    tags:
      - source:adidas
      - format:openapi
      - spec:paths
      - spec:responses
      - spec:media-types
      - experience:consistency
      - experience:data-modeling
  ok-response-use-hal-or-problem-json:
    description: 'All success responses MUST be of media type `application/hal+json`
      or `application/problem+json`. It requires the targeted value to be one of
      ["application/hal+json","application/problem+json"] (evaluated at
      `$.paths..responses[?( @property == 200 )].content[*]~`). Severity:
      error.'
    severity: error
    given: $.paths..responses[?( @property == 200 )].content[*]~
    recommended: true
    formats:
      - oas3
    message: "Response documents MUST be of application/hal+json or
      application/problem+json media types: {{error}}"
    then:
      function: enumeration
      functionOptions:
        values:
          - application/hal+json
          - application/problem+json
    tags:
      - source:adidas
      - format:openapi
      - spec:paths
      - spec:responses
      - spec:media-types
      - experience:consistency
      - experience:data-modeling
  success-response-match-hal-schema:
    description: 'All success responses MUST follow `application/hal+json` schema.
      It validates the `schema` field against a JSON Schema (evaluated at
      `$.paths..responses[?( @property == 200 && @property < 300 && @property !=
      204)].content[?(@property === "application/hal+json")]`). Severity:
      error.'
    severity: error
    given: $.paths..responses[?( @property == 200 && @property < 300 && @property !=
      204)].content[?(@property === "application/hal+json")]
    recommended: true
    type: style
    formats:
      - oas3
    message: "Response documents MUST follow application/hal+json schema: {{error}}"
    then:
      field: schema
      function: schema
      functionOptions:
        schema:
          $ref: ./supermodel/adidas/api/HAL.yaml
    tags:
      - source:adidas
      - format:openapi
      - spec:paths
      - spec:responses
      - spec:media-types
      - experience:data-modeling
      - experience:consistency
  get-no-request-body:
    description: "GET requests MUST NOT have a request body. It requires the
      targeted value to be absent or empty (evaluated at
      `$.paths[*].get.requestBody`). Severity: error."
    severity: error
    recommended: true
    formats:
      - oas3
    given: $.paths[*].get.requestBody
    then:
      function: falsy
      message: "{{description}}: {{error}}"
    tags:
      - source:adidas
      - format:openapi
      - spec:paths
      - spec:operations
      - spec:request-body
      - experience:consistency
      - experience:usability
  post-not-for-retrieval:
    description: "POST requests SHOULD NOT be used for retrieving information. Use
      GET instead. It requires the `summary` field not to match
      `(retrieve|fetch|get|read)` (evaluated at `$.paths[*].post`). Severity:
      error."
    severity: error
    recommended: true
    formats:
      - oas3
    given: $.paths[*].post
    then:
      field: summary
      function: pattern
      functionOptions:
        notMatch: (retrieve|fetch|get|read)
      message: "{{description}}: {{error}}"
    tags:
      - source:adidas
      - format:openapi
      - spec:paths
      - spec:operations
      - experience:consistency
      - experience:usability
  put-require-request-body:
    description: "PUT requests MUST have a request body. It requires the
      `requestBody` field to be present and non-empty (evaluated at
      `$.paths[*].put`). Severity: error."
    severity: error
    recommended: true
    formats:
      - oas3
    given: $.paths[*].put
    then:
      field: requestBody
      function: truthy
      message: "{{description}}: {{error}}"
    tags:
      - source:adidas
      - format:openapi
      - spec:paths
      - spec:operations
      - experience:consistency
      - experience:usability
  delete-no-request-body:
    description: "DELETE requests MUST NOT have a request body. It requires the
      targeted value to be absent or empty (evaluated at
      `$.paths[*].delete.requestBody`). Severity: error."
    severity: error
    recommended: true
    formats:
      - oas3
    given: $.paths[*].delete.requestBody
    then:
      function: falsy
      message: "{{description}}: {{error}}"
    tags:
      - source:adidas
      - format:openapi
      - spec:paths
      - spec:operations
      - spec:request-body
      - experience:consistency
      - experience:usability
  paths-no-verbs:
    description: "API paths MUST be resource-focused and MUST NOT include verbs like
      'get', 'update', 'create', or 'delete'. It requires the targeted value not
      to match `/\\b(get|update|create|delete|fetch|retrieve)\\b/` (evaluated at
      `$.paths[*]~`). Severity: warn."
    severity: warn
    recommended: true
    formats:
      - oas3
    message: Path '{{path}}' includes a verb (e.g., 'get', 'update', 'create',
      'delete'). API paths SHOULD be resource-focused.
    given: $.paths[*]~
    then:
      function: pattern
      functionOptions:
        notMatch: /\b(get|update|create|delete|fetch|retrieve)\b/
    tags:
      - source:adidas
      - format:openapi
      - spec:paths
      - experience:naming
      - experience:consistency
  require-realistic-examples:
    description: "API design SHOULD include real-like examples for request and
      response definitions. It requires the `example` field to be present and
      non-empty (evaluated at `$..[?(@.example || @.examples)]`). Severity:
      warn."
    severity: warn
    recommended: true
    formats:
      - oas3
    message: The {{property}} SHOULD include a real-like example. Add realistic
      examples to improve API usability.
    given: $..[?(@.example || @.examples)]
    then:
      field: example
      function: truthy
    tags:
      - source:adidas
      - format:openapi
      - spec:examples
      - experience:documentation
      - experience:usability
  version-semantic-and-stable:
    description: "The API contract MUST have a stable version and MUST follow
      semantic versioning (e.g., '1.0.0'). Words like 'SNAPSHOT' or 'RELEASE'
      are not allowed. It requires the targeted value to match the pattern
      `^(?!.*\\b(SNAPSHOT|RELEASE)\\b)(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\
      \\d*)$` (evaluated at `$.info.version`). Severity: error."
    severity: error
    recommended: true
    formats:
      - oas3
    message: "{{description}}: {{error}}"
    given: $.info.version
    then:
      function: pattern
      functionOptions:
        match: ^(?!.*\b(SNAPSHOT|RELEASE)\b)(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$
    tags:
      - source:adidas
      - format:openapi
      - spec:info
      - experience:versioning
      - experience:consistency
  require-root-security:
    description: "The API contract MUST include a 'security' section at the root
      level. It requires the `security` field to be present and non-empty
      (evaluated at `$`). Severity: error."
    severity: error
    recommended: true
    formats:
      - oas3
    message: "{{description}}: {{error}}"
    given: $
    then:
      field: security
      function: truthy
    tags:
      - source:adidas
      - format:openapi
      - spec:document
      - experience:security
      - experience:governance
  require-components-section:
    description: "The API contract MUST include a 'components' section. It requires
      the `components` field to be present and non-empty (evaluated at `$`).
      Severity: error."
    severity: error
    recommended: true
    formats:
      - oas3
    message: "{{description}}: {{error}}"
    given: $
    then:
      field: components
      function: truthy
    tags:
      - source:adidas
      - format:openapi
      - spec:document
      - experience:consistency
      - experience:governance
  require-security-schemes:
    description: "The API contract MUST include a 'securitySchemes' subsection under
      the 'components' section. It requires the `securitySchemes` field to be
      present and non-empty (evaluated at `$.components`). Severity: error."
    severity: error
    recommended: true
    formats:
      - oas3
    message: "{{description}}: {{error}}"
    given: $.components
    then:
      field: securitySchemes
      function: truthy
    tags:
      - source:adidas
      - format:openapi
      - spec:components
      - experience:security
      - experience:governance
      - source:api-evangelist
  info-require-leanix-id:
    description: "The API contract SHOULD include a custom field 'x-leanixid' in the
      'info' section. It requires the `x-leanixid` field to be present and
      non-empty (evaluated at `$.info`). Severity: warn."
    severity: warn
    recommended: true
    formats:
      - oas3
    message: "{{description}}: {{error}}"
    given: $.info
    then:
      field: x-leanixid
      function: truthy
    tags:
      - source:adidas
      - format:openapi
      - spec:info
      - experience:governance
      - experience:discoverability
  leanix-id-valid-uuid:
    description: "The API contract SHOULD include a custom field 'x-leanixid'
      containing a valid UUID. It requires the targeted value to match the
      pattern
      `^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]\
      {12}$` (evaluated at `$.info.x-leanixid`). Severity: warn."
    severity: warn
    recommended: true
    formats:
      - oas3
    message: "{{description}}: {{error}}"
    given: $.info.x-leanixid
    then:
      function: pattern
      functionOptions:
        match: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
    tags:
      - source:adidas
      - format:openapi
      - spec:info
      - experience:governance
      - experience:consistency
  info-require-gateway:
    description: "The API contract SHOULD include a custom field 'x-gateway' in the
      'info' section. It requires the `x-gateway` field to be present and
      non-empty (evaluated at `$.info`). Severity: warn."
    severity: warn
    recommended: true
    formats:
      - oas3
    message: "{{description}}: {{error}}"
    given: $.info
    then:
      field: x-gateway
      function: truthy
    tags:
      - source:adidas
      - format:openapi
      - spec:info
      - experience:governance
  gateway-from-allowed-list:
    description: "The 'x-gateway' property, if present, MUST have a value in the
      enumeration: kong, nginx, aws, akamai, sap, other. It requires the
      `x-gateway` field to be one of
      [\"kong\",\"nginx\",\"aws\",\"akamai\",\"sap\",\"other\"] (evaluated at
      `$`). Severity: warn."
    severity: warn
    recommended: true
    formats:
      - oas3
    given: $
    then:
      field: x-gateway
      function: enumeration
      functionOptions:
        values:
          - kong
          - nginx
          - aws
          - akamai
          - sap
          - other
    tags:
      - source:adidas
      - format:openapi
      - spec:document
      - experience:governance
      - experience:consistency
  responses-include-hypermedia-links:
    description: "The API contract MAY include hypermedia links to represent the
      state of resources and be navigable. It requires the `links` field to be
      present and non-empty (evaluated at `$.paths[*][*].responses[*]`).
      Severity: hint."
    severity: hint
    recommended: true
    formats:
      - oas3
    message: "{{description}}: {{error}}"
    given: $.paths[*][*].responses[*]
    then:
      field: links
      function: truthy
    tags:
      - source:adidas
      - format:openapi
      - spec:paths
      - spec:responses
      - experience:discoverability
      - experience:usability
  uri-versioning-single-version:
    message: Path can contain correct URI versioning
    description: "CAN use correct URI versioning [115a]. It requires the targeted
      value to match the pattern `^((?!.*\\/v\\d+(\\/.*)?\\/v\\d+)\\/.*)$`
      (evaluated at `$.paths.*~`). Severity: error."
    documentationUrl: https://github.com/baloise-incubator/spectral-ruleset/blob/main/doc/rules/can-use-correct-URI-versioning.test.md
    severity: error
    given: $.paths.*~
    then:
      function: pattern
      functionOptions:
        match: ^((?!.*\/v\d+(\/.*)?\/v\d+)\/.*)$
    tags:
      - source:baloise
      - format:openapi
      - spec:paths
      - experience:versioning
      - experience:consistency
  property-names-camel-case:
    message: Property name has to be ASCII camelCase
    description: "MUST property names must be ASCII camelCase [118a]. It requires
      the targeted value to match the pattern
      `^[a-z]+((\\d)|([A-Z0-9][a-z0-9]+))*([A-Z])?$` (evaluated at
      `$.paths.*.*[responses,requestBody]..content..schema..properties.*~`).
      Severity: error."
    documentationUrl: https://github.com/baloise-incubator/spectral-ruleset/blob/main/doc/rules/property-names-must-be-ascii-camel-case.md
    severity: error
    given: $.paths.*.*[responses,requestBody]..content..schema..properties.*~
    then:
      function: pattern
      functionOptions:
        match: ^[a-z]+((\d)|([A-Z0-9][a-z0-9]+))*([A-Z])?$
    tags:
      - source:baloise
      - format:openapi
      - spec:paths
      - spec:request-body
      - spec:responses
      - spec:media-types
      - spec:schemas
      - experience:naming
      - experience:consistency
  use-standard-status-codes:
    message: "{{property}} is not a standardized response code"
    description: 'MUST use standard HTTP status codes [150a]. It requires the
      targeted value to be one of
      ["100","101","200","201","202","203","204","205","206","207","300","301","302","303","304","305","307","400","401","402","403","404","405","406","407","408","409","410","411","412","413","414","415","416","417","422","423","426","428","429","431","500","501","502","503","504","505","511","default"]
      (evaluated at `$.paths.*.*.responses.*~`). Severity: error.'
    documentationUrl: https://github.com/baloise-incubator/spectral-ruleset/blob/main/doc/rules/must-use-additional-standard-http-status-codes.md
    severity: error
    given: $.paths.*.*.responses.*~
    then:
      function: enumeration
      functionOptions:
        values:
          - "100"
          - "101"
          - "200"
          - "201"
          - "202"
          - "203"
          - "204"
          - "205"
          - "206"
          - "207"
          - "300"
          - "301"
          - "302"
          - "303"
          - "304"
          - "305"
          - "307"
          - "400"
          - "401"
          - "402"
          - "403"
          - "404"
          - "405"
          - "406"
          - "407"
          - "408"
          - "409"
          - "410"
          - "411"
          - "412"
          - "413"
          - "414"
          - "415"
          - "416"
          - "417"
          - "422"
          - "423"
          - "426"
          - "428"
          - "429"
          - "431"
          - "500"
          - "501"
          - "502"
          - "503"
          - "504"
          - "505"
          - "511"
          - default
    tags:
      - source:baloise
      - format:openapi
      - spec:paths
      - spec:responses
      - experience:error-handling
      - experience:consistency
  prefer-400-over-422:
    message: Prefer 400 over 422 as response code
    description: "MUST use standard HTTP status codes [150a]. It requires the `422`
      field to be defined (evaluated at `$.paths.*.*.responses.422`). Severity:
      warn."
    documentationUrl: https://github.com/baloise-incubator/spectral-ruleset/blob/main/doc/rules/must-use-additional-standard-http-status-codes.md
    severity: warn
    given: $.paths.*.*.responses.422
    then:
      field: "422"
      function: defined
    tags:
      - source:baloise
      - format:openapi
      - spec:paths
      - spec:responses
      - experience:error-handling
      - experience:consistency
  operation-well-understood-status-codes:
    message: "{{error}}"
    description: "MUST use standard HTTP status codes [150]. It applies a custom
      validation to the targeted value (evaluated at `$.paths.*`). Severity:
      warn."
    documentationUrl: https://github.com/baloise-incubator/spectral-ruleset/blob/main/doc/rules/should-use-additional-well-understood-http-status-codes.md
    severity: warn
    given: $.paths.*
    then:
      function: baloise:assert-http-codes-for-operation
      functionOptions:
        wellUnderstood:
          "200":
            - ALL
          "201":
            - POST
            - PUT
          "202":
            - POST
            - PUT
            - DELETE
            - PATCH
          "204":
            - PUT
            - DELETE
            - PATCH
          "207":
            - POST
          "301":
            - ALL
          "303":
            - PATCH
            - POST
            - PUT
            - DELETE
          "304":
            - GET
            - HEAD
          "400":
            - ALL
          "401":
            - ALL
          "403":
            - ALL
          "404":
            - ALL
          "405":
            - ALL
          "406":
            - ALL
          "408":
            - ALL
          "409":
            - POST
            - PUT
            - DELETE
            - PATCH
          "410":
            - ALL
          "412":
            - PUT
            - DELETE
            - PATCH
          "415":
            - POST
            - PUT
            - DELETE
            - PATCH
          "422":
            - ALL
          "423":
            - PUT
            - DELETE
            - PATCH
          "428":
            - ALL
          "429":
            - ALL
          "500":
            - ALL
          "501":
            - ALL
          "503":
            - ALL
          default:
            - ALL
    tags:
      - source:baloise
      - format:openapi
      - spec:paths
      - experience:error-handling
      - experience:consistency
  require-tracing-headers:
    message: Header X-B3-Traceid, X-B3-Spanid or traceparent (w3c) missing
    description: "MUST use b3 or w3c tracing [233a]. It applies a custom validation
      to the targeted value (evaluated at `$.paths.*`). Severity: error."
    documentationUrl: https://github.com/baloise-incubator/spectral-ruleset/blob/main/doc/rules/requests-must-use-tracing.md
    severity: error
    given: $.paths.*
    then:
      function: baloise:validate-tracing
    tags:
      - source:baloise
      - format:openapi
      - spec:paths
      - experience:reliability
      - experience:governance
  info-require-audience:
    message: Missing or wrong `info.x-audience`.
    description: "MUST provide API audience [219]. It requires the `x-audience`
      field to be present and non-empty, and requires the `x-audience` field to
      match the pattern
      `^(team-internal|domain-internal|company-internal|external-partner|extern\
      al-public)$` (evaluated at `$.info`). Severity: error."
    documentationUrl: https://github.com/baloise-incubator/spectral-ruleset/blob/main/doc/rules/property-names-must-be-ascii-camel-case.md
    severity: error
    given: $.info
    then:
      - field: x-audience
        function: truthy
      - field: x-audience
        function: pattern
        functionOptions:
          match: ^(team-internal|domain-internal|company-internal|external-partner|external-public)$
    tags:
      - source:baloise
      - format:openapi
      - spec:info
      - experience:governance
      - experience:discoverability
  query-parameters-camel-case:
    message: Query parameter name has to be ASCII camelCase
    description: "MUST query parameter names must be ASCII camelCase [130a]. It
      requires the targeted value to match the pattern
      `^[a-z]+((\\d)|([A-Z0-9][a-z0-9]+))*([A-Z])?$` (evaluated at
      `$.paths.*.*.parameters[?(@ && @.in=='query')].name`). Severity: error."
    documentationUrl: https://github.com/baloise-incubator/spectral-ruleset/blob/main/doc/rules/query-parameter-names-must-be-ascii-camel-case.md
    severity: error
    given: $.paths.*.*.parameters[?(@ && @.in=='query')].name
    then:
      function: pattern
      functionOptions:
        match: ^[a-z]+((\d)|([A-Z0-9][a-z0-9]+))*([A-Z])?$
    tags:
      - source:baloise
      - format:openapi
      - spec:paths
      - spec:parameters
      - experience:naming
      - experience:consistency
  responses-include-ratelimit-headers:
    description: "Response must include ratelimit-x headers. It requires the
      `headers.ratelimit-limit` field to be present and non-empty, and requires
      the `headers.ratelimit-remaining` field to be present and non-empty, and
      requires the `headers.ratelimit-reset` field to be present and non-empty
      (evaluated at `$..responses.*`). Severity: error."
    message: "{{description}}; missing {{property}}"
    severity: error
    given: $..responses.*
    then:
      - field: headers.ratelimit-limit
        function: truthy
      - field: headers.ratelimit-remaining
        function: truthy
      - field: headers.ratelimit-reset
        function: truthy
    tags:
      - source:digitalocean
      - format:openapi
      - spec:responses
      - experience:reliability
      - experience:documentation
  properties-require-examples:
    description: "Object properties must include examples. It applies a custom
      validation to the targeted value (evaluated at
      `$..properties..properties.*`). Severity: error."
    given: $..properties..properties.*
    severity: error
    message: "{{description}}; {{property}}"
    then:
      function: digitalocean:ensurePropertiesExample
    tags:
      - source:digitalocean
      - format:openapi
      - spec:schemas
      - experience:documentation
      - experience:usability
  parameters-require-examples:
    description: 'Parameters must include examples. It requires exactly one of
      ["example","examples"] to be present (evaluated at `$..parameters.*`).
      Severity: error.'
    given: $..parameters.*
    severity: error
    message: "{{description}}; missing {{property}}"
    then:
      function: xor
      functionOptions:
        properties:
          - example
          - examples
    tags:
      - source:digitalocean
      - format:openapi
      - spec:parameters
      - experience:documentation
      - experience:usability
  headers-require-examples:
    description: "Headers must include examples. It applies a custom validation to
      the targeted value (evaluated at `$..headers.*`). Severity: error."
    given: $..headers.*
    severity: error
    message: "{{description}}; missing {{property}}"
    then:
      function: digitalocean:ensurePropertiesExample
    tags:
      - source:digitalocean
      - format:openapi
      - spec:headers
      - experience:documentation
      - experience:usability
  operations-use-ref:
    description: "Endpoint must be a $ref. It requires the `$ref` field to be
      present and non-empty (evaluated at `$.paths.*.*`). Severity: error."
    message: "{{description}}; {{property}} incorrect"
    severity: error
    resolved: false
    given: $.paths.*.*
    then:
      field: $ref
      function: truthy
    tags:
      - source:digitalocean
      - format:openapi
      - spec:paths
      - experience:consistency
      - experience:governance
  paths-include-version:
    description: "Path must include the version. It requires the targeted value to
      match the pattern `^(/v[12]/.*|/api/v[12]/.*)$` (evaluated at
      `$.paths[?(@property!='/<upload_url>')]~`). Severity: error."
    message: "{{description}}; {{property}} incorrect"
    severity: error
    resolved: false
    given: $.paths[?(@property!='/<upload_url>')]~
    then:
      function: pattern
      functionOptions:
        match: ^(/v[12]/.*|/api/v[12]/.*)$
    tags:
      - source:digitalocean
      - format:openapi
      - spec:paths
      - experience:versioning
      - experience:consistency
  operation-ref-resource-file:
    description: "Endpoint must a $ref to a file in resources/. It requires the
      targeted value to match the pattern `^resources/.*yml$` (evaluated at
      `$.paths.*.$ref`). Severity: error."
    message: "{{description}}; {{value}} incorrect"
    severity: error
    resolved: false
    given: $.paths.*.$ref
    then:
      function: pattern
      functionOptions:
        match: ^resources/.*yml$
    tags:
      - source:digitalocean
      - format:openapi
      - spec:paths
      - experience:consistency
      - experience:governance
  responses-define-401:
    description: "Responses should contain common response - 401 (unauthorized). It
      requires the `401` field to be present and non-empty (evaluated at
      `$.paths..responses`). Severity: error."
    message: "{{description}}. Missing {{property}}"
    severity: error
    given: $.paths..responses
    then:
      field: "401"
      function: truthy
    tags:
      - source:digitalocean
      - format:openapi
      - spec:paths
      - spec:responses
      - experience:error-handling
      - experience:documentation
  responses-define-404:
    description: "Responses should contain common response - 404 (not found). It
      requires the `404` field to be present and non-empty (evaluated at
      `$.paths[?(@property.match(/.*\\/{.*}.*/))]..responses`). Severity:
      error."
    message: "{{description}}. Missing {{property}}"
    severity: error
    given: $.paths[?(@property.match(/.*\/{.*}.*/))]..responses
    then:
      field: "404"
      function: truthy
    tags:
      - source:digitalocean
      - format:openapi
      - spec:paths
      - spec:responses
      - experience:error-handling
      - experience:documentation
  responses-define-429:
    description: "Responses should contain common response - 429 (too many
      requests). It requires the `429` field to be present and non-empty
      (evaluated at `$.paths..responses`). Severity: error."
    message: "{{description}}. Missing {{property}}"
    severity: error
    given: $.paths..responses
    then:
      field: "429"
      function: truthy
    tags:
      - source:digitalocean
      - format:openapi
      - spec:paths
      - spec:responses
      - experience:error-handling
      - experience:relia

# --- truncated at 32 KB (242 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/spotlight-rules/refs/heads/main/rules/spotlight-rules-recommended.yml