Snow Software API Rules

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

  # Region variable in server
  snow-server-region-variable:
    description: Snow Atlas server URLs should include a {region} variable for multi-region support
    message: "Server URL should include {region} variable for Snow Atlas multi-region"
    severity: warn
    given: "$.servers[*].url"
    then:
      function: pattern
      functionOptions:
        match: ".*\\{region\\}.*"

  # Pagination parameters
  snow-pagination-params:
    description: Collection endpoints should support page_number and page_size parameters
    message: "Collection GET operations should support pagination parameters"
    severity: info
    given: "$.paths[*].get.parameters[*].name"
    then:
      function: pattern
      functionOptions:
        match: "^(page_number|page_size|filter|sort)$"

  # Filter parameter
  snow-filter-param:
    description: Snow Atlas APIs should support filter query parameters for collection endpoints
    message: "Collection GET endpoints should support a filter parameter"
    severity: info
    given: "$.paths[*].get"
    then:
      field: parameters
      function: truthy

  # Tag requirements
  snow-operation-tag:
    description: All operations must have at least one tag
    message: "Operation must have at least one tag"
    severity: warn
    given: "$.paths[*][get,post,put,delete,patch]"
    then:
      field: tags
      function: truthy

  # Summary requirements
  snow-operation-summary:
    description: All operations must have a summary in Title Case
    message: "Operation must have a summary"
    severity: warn
    given: "$.paths[*][get,post,put,delete,patch]"
    then:
      field: summary
      function: truthy

  # Description requirements
  snow-operation-description:
    description: All operations should have a description
    message: "Operation should have a description"
    severity: info
    given: "$.paths[*][get,post,put,delete,patch]"
    then:
      field: description
      function: truthy

  # HATEOAS response pattern
  snow-hateoas-response:
    description: Snow Atlas collection responses follow a HATEOAS pattern with pagination links
    message: "200 response should have a defined schema"
    severity: info
    given: "$.paths[*][get].responses['200'].content['application/json'].schema"
    then:
      function: truthy

  # Error response definitions
  snow-400-error-defined:
    description: Operations should define a 400 Bad Request response
    message: "Operation should define a 400 response"
    severity: info
    given: "$.paths[*][post,put,patch].responses"
    then:
      field: "400"
      function: truthy