Stanley Black & Decker API Rules

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

  sbd-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 &+]*$"

  sbd-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
  sbd-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
  sbd-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

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

  sbd-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

  sbd-not-found-response:
    description: Operations with path parameters should define a 404 response
    message: "Operation with path parameters should define a 404 Not Found response"
    severity: warn
    given: "$.paths[*][*][?(@.parameters[*].in=='path')]"
    then:
      field: "responses.404"
      function: truthy

  sbd-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
  sbd-operation-tags-required:
    description: All operations must have at least one tag
    message: "Operation must include at least one tag for categorization"
    severity: warn
    given: "$.paths[*][*].tags"
    then:
      function: length
      functionOptions:
        min: 1

  sbd-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
  sbd-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{}-]*$"

  sbd-path-plural-nouns:
    description: Collection resource paths should use plural nouns
    message: "Collection paths should use plural nouns (tools, batteries, assets, jobsites)"
    severity: warn
    given: "$.paths"
    then:
      function: pattern
      functionOptions:
        match: "^/v[0-9]+/[a-z].*"

  # Parameter requirements
  sbd-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

  sbd-parameter-descriptions:
    description: All parameters must have descriptions
    message: "Parameter must have a description"
    severity: warn
    given: "$.paths[*][*].parameters[*]"
    then:
      field: description
      function: truthy

  # Schema requirements
  sbd-schemas-have-properties:
    description: Schema objects should define properties
    message: "Schema component should define properties"
    severity: warn
    given: "$.components.schemas[*]"
    then:
      field: properties
      function: truthy

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

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

  sbd-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

  sbd-external-docs:
    description: API should reference external documentation
    message: "API should include externalDocs pointing to official documentation"
    severity: info
    given: "$"
    then:
      field: externalDocs
      function: truthy