Stellar Cyber API Rules

extends: spectral:oas
rules:
  stellar-cyber-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]*)*$"

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

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

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

  stellar-cyber-security-defined:
    description: All operations should have security requirements defined
    message: Operations should define security requirements
    severity: warn
    given: "$.paths[*][*]"
    then:
      field: security
      function: defined

  stellar-cyber-bearer-auth-only:
    description: Stellar Cyber uses JWT Bearer authentication exclusively
    message: Security scheme must use bearerAuth
    severity: error
    given: "$.components.securitySchemes"
    then:
      field: bearerAuth
      function: truthy

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

  stellar-cyber-request-body-described:
    description: Request bodies on POST/PUT operations should have descriptions
    message: Request body content should be described
    severity: warn
    given: "$.paths[*][post,put].requestBody"
    then:
      field: description
      function: defined

  stellar-cyber-parameters-have-descriptions:
    description: All parameters should have descriptions
    message: "Parameter '{{value}}' is missing a description"
    severity: warn
    given: "$.paths[*][*].parameters[*]"
    then:
      field: description
      function: truthy

  stellar-cyber-no-empty-descriptions:
    description: Descriptions must not be empty
    message: Description must not be empty
    severity: warn
    given: "$..[description]"
    then:
      function: truthy

  stellar-cyber-4xx-responses:
    description: Operations should define 401 unauthorized response
    message: Operations should define a 401 response for authentication failures
    severity: warn
    given: "$.paths[*][*].responses"
    then:
      field: "401"
      function: defined