Squarespace API Rules

extends: spectral:oas
rules:
  # Squarespace APIs use cursor-based pagination — enforce cursor parameter on list endpoints
  squarespace-list-endpoint-cursor:
    description: List (GET collection) endpoints must support cursor-based pagination
    message: GET collection endpoint is missing cursor parameter for pagination
    severity: warn
    given: $.paths[?([email protected](/\{[^}]+\}$/))].get
    then:
      field: parameters
      function: defined

  # All operations require operationId
  squarespace-operation-id-required:
    description: All operations must have an operationId
    message: Operation is missing operationId
    severity: error
    given: $.paths[*][*]
    then:
      field: operationId
      function: defined

  # Operation IDs should use camelCase
  squarespace-operation-id-camel-case:
    description: Operation IDs must use camelCase
    message: 'Operation ID "{{value}}" should be camelCase'
    severity: warn
    given: $.paths[*][*].operationId
    then:
      function: pattern
      functionOptions:
        match: '^[a-z][a-zA-Z0-9]*$'

  # All operations must have summaries
  squarespace-operation-summary-required:
    description: All operations must have a summary
    message: Operation is missing summary
    severity: error
    given: $.paths[*][*]
    then:
      field: summary
      function: defined

  # Summaries must use Title Case
  squarespace-summary-title-case:
    description: Operation summaries must use Title Case
    message: 'Summary "{{value}}" should use Title Case'
    severity: warn
    given: $.paths[*][*].summary
    then:
      function: pattern
      functionOptions:
        match: '^[A-Z][a-zA-Z0-9]*(\s[A-Z][a-zA-Z0-9]*)*$'

  # All operations must have descriptions
  squarespace-operation-description-required:
    description: All operations must have a description
    message: Operation is missing description
    severity: warn
    given: $.paths[*][*]
    then:
      field: description
      function: defined

  # All operations should have tags
  squarespace-operation-tags-required:
    description: All operations must have tags
    message: Operation is missing tags
    severity: warn
    given: $.paths[*][*]
    then:
      field: tags
      function: defined

  # Tags must use Title Case
  squarespace-tags-title-case:
    description: All tags must use Title Case
    message: 'Tag "{{value}}" should use Title Case'
    severity: warn
    given: $.tags[*].name
    then:
      function: pattern
      functionOptions:
        match: '^[A-Z][a-zA-Z0-9]*(\s[A-Z][a-zA-Z0-9]*)*$'

  # API paths must start with /commerce
  squarespace-paths-commerce-prefix:
    description: Squarespace Commerce API paths should start with /commerce
    message: 'Path "{{path}}" should begin with /commerce'
    severity: info
    given: $.paths
    then:
      field: '@key'
      function: pattern
      functionOptions:
        match: '^\/commerce\/'

  # Bearer auth must be used
  squarespace-bearer-auth:
    description: Squarespace APIs use Bearer token authentication
    message: API must define bearerAuth security scheme
    severity: error
    given: $.components.securitySchemes
    then:
      field: bearerAuth
      function: defined

  # 401 unauthorized should be defined for secured endpoints
  squarespace-401-response:
    description: Secured endpoints should document 401 Unauthorized responses
    message: Secured endpoint is missing 401 response
    severity: warn
    given: $.paths[*][*].responses
    then:
      field: '401'
      function: defined

  # JSON responses should use application/json content type
  squarespace-json-response-content-type:
    description: Success responses must use application/json content type
    message: 200 response must return application/json
    severity: error
    given: $.paths[*][*].responses['200'].content
    then:
      field: 'application/json'
      function: defined