StepZen API Rules

extends: spectral:oas
rules:
  stepzen-operation-summary-title-case:
    description: All operation summaries must use Title Case
    message: "Operation summary '{{value}}' must 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]*)*$"

  stepzen-tags-required:
    description: All operations must have at least one tag
    message: Operations must include tags
    severity: error
    given: "$.paths[*][*]"
    then:
      field: tags
      function: truthy

  stepzen-response-200-required:
    description: GET operations must return 200
    message: GET operations must define a 200 response
    severity: error
    given: "$.paths[*].get"
    then:
      field: responses.200
      function: truthy

  stepzen-api-key-auth:
    description: StepZen uses API key authentication
    message: Security scheme must include apiKeyAuth
    severity: error
    given: "$.components.securitySchemes"
    then:
      field: apiKeyAuth
      function: truthy

  stepzen-operation-ids-camel-case:
    description: OperationIds must use camelCase
    message: "OperationId '{{value}}' must use camelCase"
    severity: warn
    given: "$.paths[*][*].operationId"
    then:
      function: pattern
      functionOptions:
        match: "^[a-z][a-zA-Z0-9]*$"

  stepzen-path-kebab-case:
    description: Path segments must use kebab-case
    message: "Path '{{value}}' must use kebab-case"
    severity: warn
    given: "$.paths"
    then:
      field: "@key"
      function: pattern
      functionOptions:
        match: "^(\\/([a-z][a-z0-9-]*(\\{[a-zA-Z]+\\})?)*)*$"

  stepzen-401-responses:
    description: Operations must handle 401 unauthorized
    message: Operations must define a 401 response
    severity: warn
    given: "$.paths[*][*].responses"
    then:
      field: "401"
      function: defined

  stepzen-descriptions-required:
    description: Operations must have descriptions
    message: Operation is missing a description
    severity: error
    given: "$.paths[*][*]"
    then:
      field: description
      function: truthy