extends:
  - spectral:oas
formats:
  - oas3
documentationUrl: https://developer.shodan.io/
rules:
  shodan-info-contact:
    description: Shodan APIs must declare a contact with email and URL.
    severity: error
    given: "$.info.contact"
    then:
      - field: email
        function: truthy
      - field: url
        function: truthy

  shodan-info-license:
    description: Shodan APIs must declare a license referencing the Shodan ToS.
    severity: error
    given: "$.info.license"
    then:
      - field: name
        function: truthy
      - field: url
        function: truthy

  shodan-server-https:
    description: All Shodan servers must be HTTPS endpoints under shodan.io.
    severity: error
    given: "$.servers[*].url"
    then:
      function: pattern
      functionOptions:
        match: "^https://[a-z0-9.-]*shodan\\.io"

  shodan-security-apikey:
    description: All authenticated Shodan APIs must use the `apiKey` query-parameter scheme named `key`.
    severity: warn
    given: "$.components.securitySchemes[?(@.type=='apiKey')]"
    then:
      - field: in
        function: pattern
        functionOptions:
          match: "^query$"
      - field: name
        function: pattern
        functionOptions:
          match: "^key$"

  shodan-operation-tags:
    description: Every operation must declare at least one tag.
    severity: error
    given: "$.paths[*][get,post,put,delete,patch]"
    then:
      field: tags
      function: truthy

  shodan-operation-operationId:
    description: Every operation must have a camelCase operationId.
    severity: error
    given: "$.paths[*][get,post,put,delete,patch]"
    then:
      field: operationId
      function: pattern
      functionOptions:
        match: "^[a-z][a-zA-Z0-9]+$"

  shodan-operation-summary-title-case:
    description: Operation summaries should use Title Case.
    severity: warn
    given: "$.paths[*][get,post,put,delete,patch].summary"
    then:
      function: pattern
      functionOptions:
        match: "^(?:[A-Z][a-zA-Z0-9]*(?: [A-Z][a-zA-Z0-9]*| (?:and|or|of|to|for|in|on|by|the|a|an|with|from|at|as)| [A-Z]+)*)$"

  shodan-operation-description:
    description: Operations should have a description.
    severity: warn
    given: "$.paths[*][get,post,put,delete,patch]"
    then:
      field: description
      function: truthy

  shodan-response-200:
    description: GET operations must define a 200 response.
    severity: error
    given: "$.paths[*].get"
    then:
      field: responses.200
      function: truthy

  shodan-parameter-description:
    description: Path and query parameters should be described.
    severity: warn
    given: "$.paths[*][get,post,put,delete,patch].parameters[*]"
    then:
      field: description
      function: truthy

  shodan-tag-defined:
    description: Tags used on operations must be defined at the document level.
    severity: warn
    given: "$"
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          required: [tags]
          properties:
            tags:
              type: array
              minItems: 1