Cloudsmith API Rules

extends:
  - spectral:oas

# Spectral linting rules for the Cloudsmith API (v1).
# Validates Cloudsmith conventions: api.cloudsmith.io host, "token"
# Authorization scheme, page/page_size pagination, owner/repo path
# parameters, and JSON content types.
rules:
  cloudsmith-info-contact:
    description: API contact information must be present.
    severity: error
    given: "$.info"
    then:
      field: contact
      function: truthy

  cloudsmith-info-license:
    description: API license must be declared.
    severity: warn
    given: "$.info"
    then:
      field: license
      function: truthy

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

  cloudsmith-host:
    description: Cloudsmith APIs must be served from api.cloudsmith.io.
    severity: warn
    given: "$.servers[*].url"
    then:
      function: pattern
      functionOptions:
        match: "api\\.cloudsmith\\.io"

  cloudsmith-auth-required:
    description: A security scheme must be declared (token-based apiKey).
    severity: error
    given: "$.components.securitySchemes"
    then:
      function: truthy

  cloudsmith-token-prefix:
    description: API key descriptions should mention the "token" Authorization prefix.
    severity: info
    given: "$.components.securitySchemes[*]"
    then:
      field: description
      function: pattern
      functionOptions:
        match: "(?i)token"

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

  cloudsmith-operation-summary:
    description: Every operation must include a short summary.
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: summary
      function: truthy

  cloudsmith-operation-tags:
    description: Every operation 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

  cloudsmith-known-tags:
    description: Operations should use known Cloudsmith tag groups.
    severity: info
    given: "$.paths[*][get,post,put,patch,delete].tags[*]"
    then:
      function: enumeration
      functionOptions:
        values:
          - audit-log
          - badges
          - broadcasts
          - bulk-action
          - distros
          - entitlements
          - files
          - formats
          - metrics
          - namespaces
          - orgs
          - packages
          - quota
          - rates
          - recycle-bin
          - repos
          - status
          - storage-regions
          - user
          - users
          - vulnerabilities
          - webhooks

  cloudsmith-pagination:
    description: List endpoints should support page/page_size pagination params.
    severity: info
    given: "$.paths[?(@property.match(/\\/$/))].get.parameters[*].name"
    then:
      function: enumeration
      functionOptions:
        values:
          - page
          - page_size
          - query
          - sort
          - search

  cloudsmith-owner-param:
    description: Owner-scoped paths should declare the {owner} path param.
    severity: info
    given: "$.paths[?(@property.match(/\\{owner\\}/))][*].parameters[?(@.in == 'path')].name"
    then:
      function: enumeration
      functionOptions:
        values:
          - owner
          - repo
          - identifier
          - slug
          - org
          - package
          - format

  cloudsmith-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: ["422"]

  cloudsmith-rate-limit:
    description: Rate-limited endpoints should document a 429 response.
    severity: info
    given: "$.paths[*][get,post,put,patch,delete].responses"
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          anyOf:
            - required: ["429"]
            - required: ["200"]