Sandbox Banking API Rules

extends: "spectral:oas"

rules:
  # Sandbox Banking / Glyue Integration Gateway API conventions

  sandbox-banking-operation-summary-title-case:
    description: Operation summaries must use Title Case.
    message: "Summary '{{value}}' must use Title Case (capitalize each word)."
    severity: warn
    given: "$.paths[*][*].summary"
    then:
      function: pattern
      functionOptions:
        match: "^[A-Z][a-zA-Z0-9]*(\\s[A-Z][a-zA-Z0-9]*)*$"

  sandbox-banking-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]*$"

  sandbox-banking-path-kebab-case:
    description: API path segments must use kebab-case.
    message: "Path segment must use kebab-case (lowercase with hyphens)."
    severity: warn
    given: "$.paths"
    then:
      function: pattern
      functionOptions:
        match: "^(\\/([a-z0-9-]+|\\{[a-zA-Z][a-zA-Z0-9_]*\\}))*$"

  sandbox-banking-token-auth:
    description: Glyue API uses token-based authentication via Authorization header.
    message: "API must declare TokenAuth security scheme."
    severity: error
    given: "$.components.securitySchemes"
    then:
      field: TokenAuth
      function: truthy

  sandbox-banking-response-200-schema:
    description: All 200 responses must include a content schema.
    message: "Operation '{{path}}' 200 response should include a content schema."
    severity: warn
    given: "$.paths[*][get,post,put].responses['200']"
    then:
      field: content
      function: truthy

  sandbox-banking-list-endpoint-pagination:
    description: List endpoints must support pagination parameters (page and page_size).
    message: "GET list endpoint '{{path}}' should support page and page_size query parameters."
    severity: info
    given: "$.paths[?(!@property.match(/\\{.*\\}/))][get].parameters[*].name"
    then:
      function: enumeration
      functionOptions:
        values:
          - page
          - page_size
          - status
          - start_date
          - end_date
          - integration_id

  sandbox-banking-no-trailing-slash:
    description: API paths must not end with a trailing slash.
    message: "Path '{{path}}' must not end with a trailing slash."
    severity: error
    given: "$.paths"
    then:
      function: pattern
      functionOptions:
        notMatch: "\\/$"

  sandbox-banking-tags-required:
    description: All operations must have at least one tag.
    message: "Operation '{{path}}' must declare at least one tag."
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: tags
      function: schema
      functionOptions:
        schema:
          type: array
          minItems: 1

  sandbox-banking-description-required:
    description: All operations must include a description.
    message: "Operation '{{path}}' must include a description."
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: description
      function: truthy

  sandbox-banking-401-defined:
    description: All API operations must declare a 401 Unauthorized response.
    message: "Operation '{{path}}' must define a 401 response."
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete].responses"
    then:
      field: "401"
      function: truthy

  sandbox-banking-delete-no-body:
    description: DELETE operations must not include a request body.
    message: "DELETE operation '{{path}}' must not have a request body."
    severity: error
    given: "$.paths[*][delete]"
    then:
      field: requestBody
      function: falsy

  sandbox-banking-run-endpoint-naming:
    description: Integration execution endpoints must use /run suffix.
    message: "Integration run endpoint should use '{integrationId}/run' naming pattern."
    severity: info
    given: "$.paths"
    then:
      function: pattern
      functionOptions:
        match: ".*(\\/run|\\/execute|\\/trigger).*|.*integrations.*"

  sandbox-banking-audit-trail:
    description: API must expose run-history endpoint for regulatory compliance.
    message: "Glyue API must include run-history endpoints for GLBA/FFIEC audit compliance."
    severity: error
    given: "$.paths"
    then:
      function: pattern
      functionOptions:
        match: ".*run-history.*"