Staples API Rules

extends: spectral:oas
rules:
  # Operation naming and structure
  staples-operation-ids-camel-case:
    description: Operation IDs must use camelCase naming convention
    message: "Operation ID '{{value}}' must use camelCase (e.g., searchProducts, createOrder)"
    severity: warn
    given: "$.paths[*][*].operationId"
    then:
      function: pattern
      functionOptions:
        match: "^[a-z][a-zA-Z0-9]*$"

  staples-operation-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 &]*$"

  staples-api-versioned-paths:
    description: All API paths must be versioned with /v1/ prefix
    message: "Path '{{property}}' must start with /v1/"
    severity: error
    given: "$.paths"
    then:
      function: pattern
      functionOptions:
        match: "^/v[0-9]+"

  # Authentication requirements
  staples-bearer-auth-required:
    description: All operations must use Bearer token authentication
    message: "Operation must reference bearerAuth security scheme"
    severity: error
    given: "$.paths[*][*]"
    then:
      function: schema
      functionOptions:
        schema:
          properties:
            security:
              type: array
          required:
            - security

  # Response codes
  staples-get-operations-200:
    description: GET operations must define a 200 response
    message: "GET operation must have a 200 response defined"
    severity: error
    given: "$.paths[*].get"
    then:
      field: "responses.200"
      function: truthy

  staples-post-create-201:
    description: POST create operations must return 201 Created
    message: "POST operation creating resources must return 201 Created"
    severity: error
    given: "$.paths[*].post"
    then:
      field: "responses.201"
      function: truthy

  staples-unauthorized-response:
    description: All operations must define a 401 Unauthorized response
    message: "Operation must define a 401 Unauthorized response"
    severity: error
    given: "$.paths[*][*]"
    then:
      field: "responses.401"
      function: truthy

  staples-not-found-response:
    description: Operations with path parameters should define 404
    message: "Operation with path parameters should define a 404 Not Found response"
    severity: warn
    given: "$.paths[*][*]"
    then:
      field: "responses.404"
      function: truthy

  staples-rate-limit-response:
    description: All operations must define a 429 Too Many Requests response
    message: "Operation must define a 429 Too Many Requests response"
    severity: warn
    given: "$.paths[*][*]"
    then:
      field: "responses.429"
      function: truthy

  # Tags
  staples-operation-tags-required:
    description: All operations must have at least one tag
    message: "Operation must include at least one tag"
    severity: warn
    given: "$.paths[*][*].tags"
    then:
      function: length
      functionOptions:
        min: 1

  staples-tags-title-case:
    description: All tags must use Title Case
    message: "Tag '{{value}}' must use Title Case"
    severity: warn
    given: "$.paths[*][*].tags[*]"
    then:
      function: pattern
      functionOptions:
        match: "^[A-Z][a-zA-Z0-9 ]*$"

  # Path conventions
  staples-path-kebab-case:
    description: Path segments must use kebab-case
    message: "Path must use kebab-case (lowercase, hyphens, path params)"
    severity: warn
    given: "$.paths"
    then:
      function: pattern
      functionOptions:
        match: "^[/a-z0-9{}-]*$"

  staples-no-trailing-slash:
    description: Paths must not have a trailing slash
    message: "Path '{{property}}' must not end with a trailing slash"
    severity: warn
    given: "$.paths"
    then:
      function: pattern
      functionOptions:
        notMatch: "/$"

  # Parameter requirements
  staples-path-parameters-required:
    description: Path parameters must be marked as required
    message: "Path parameter must have required: true"
    severity: error
    given: "$.paths[*][*].parameters[?(@.in=='path')]"
    then:
      field: required
      function: truthy

  staples-query-parameters-described:
    description: Query parameters must have descriptions
    message: "Query parameter must have a description"
    severity: warn
    given: "$.paths[*][*].parameters[?(@.in=='query')]"
    then:
      field: description
      function: truthy

  # Request body for POST/PUT
  staples-post-request-body:
    description: POST operations must define a request body
    message: "POST operation must include a requestBody definition"
    severity: error
    given: "$.paths[*].post"
    then:
      field: requestBody
      function: truthy

  # Schema requirements
  staples-schemas-have-descriptions:
    description: Schema components should have descriptions where possible
    message: "Schema should include descriptive information"
    severity: info
    given: "$.components.schemas[*]"
    then:
      field: type
      function: truthy

  # Info
  staples-info-contact:
    description: API must have contact information
    message: "API info must include contact details"
    severity: warn
    given: "$.info"
    then:
      field: contact
      function: truthy

  staples-info-terms:
    description: API must reference terms of service
    message: "API info should include termsOfService"
    severity: info
    given: "$.info"
    then:
      field: termsOfService
      function: truthy

  staples-info-description:
    description: API must have a description
    message: "API info must include a description"
    severity: error
    given: "$.info"
    then:
      field: description
      function: truthy

  staples-servers-defined:
    description: API must define at least one server
    message: "API must define servers with base URL"
    severity: error
    given: "$"
    then:
      field: servers
      function: truthy