Coinbase API Rules

extends:
  - spectral:oas

# Spectral linting rules for the Coinbase Developer Platform APIs
# (Advanced Trade, Exchange, Prime, Onramp, Commerce). Tuned to the
# api.coinbase.com / api.exchange.coinbase.com / api.prime.coinbase.com
# / api.commerce.coinbase.com host conventions, HMAC-SHA256 and JWT
# auth schemes, versioned URI paths, and standardized error envelopes.
rules:
  coinbase-info-contact:
    description: API contact information must be present.
    severity: error
    given: "$.info"
    then:
      field: contact
      function: truthy

  coinbase-terms-of-service:
    description: termsOfService must reference coinbase.com.
    severity: warn
    given: "$.info.termsOfService"
    then:
      function: pattern
      functionOptions:
        match: "coinbase.com"

  coinbase-server-https:
    description: All server URLs must use HTTPS.
    severity: error
    given: "$.servers[*].url"
    then:
      function: pattern
      functionOptions:
        match: "^https://"

  coinbase-server-host:
    description: Server URLs must point to a known Coinbase host.
    severity: warn
    given: "$.servers[*].url"
    then:
      function: pattern
      functionOptions:
        match: "(api\\.coinbase\\.com|api\\.exchange\\.coinbase\\.com|api\\.prime\\.coinbase\\.com|api\\.commerce\\.coinbase\\.com|api\\.developer\\.coinbase\\.com)"

  coinbase-security-defined:
    description: Authenticated APIs must declare a security scheme.
    severity: error
    given: "$.components.securitySchemes"
    then:
      function: truthy

  coinbase-security-scheme-shape:
    description: Security scheme should be apiKey, http, or oauth2.
    severity: error
    given: "$.components.securitySchemes[*]"
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          properties:
            type:
              enum: ["apiKey", "http", "oauth2"]

  coinbase-operation-id:
    description: Every operation must declare a unique operationId.
    severity: error
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: operationId
      function: truthy

  coinbase-operation-tags:
    description: Operations must declare at least one tag.
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: tags
      function: schema
      functionOptions:
        schema:
          type: array
          minItems: 1

  coinbase-operation-summary:
    description: Operations should declare a summary for documentation.
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: summary
      function: truthy

  coinbase-error-responses:
    description: Mutating operations should declare 4xx error responses.
    severity: warn
    given: "$.paths[*][post,put,patch,delete].responses"
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          anyOf:
            - required: ["400"]
            - required: ["401"]
            - required: ["403"]
            - required: ["404"]
            - required: ["429"]

  coinbase-versioned-path:
    description: Paths should be served under a versioned prefix (v1, v2, v3).
    severity: info
    given: "$.servers[*].url"
    then:
      function: pattern
      functionOptions:
        match: "/v[0-9]+|/api/v[0-9]+"

  coinbase-pagination-cursor:
    description: List operations should expose cursor-based pagination.
    severity: info
    given: "$.paths[*].get.parameters[?(@.name == 'cursor' || @.name == 'limit')]"
    then:
      field: name
      function: enumeration
      functionOptions:
        values:
          - cursor
          - limit
          - starting_after
          - ending_before