extends: spectral:oas
rules:
  # Require operationId on all operations
  operation-operationId:
    description: All operations must have an operationId.
    severity: error
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: operationId
      function: truthy

  # Require summary on all operations
  operation-summary:
    description: All operations must have a summary.
    severity: error
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: summary
      function: truthy

  # Enforce Title Case on operation summaries
  operation-summary-title-case:
    description: Operation summaries must use Title Case.
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete].summary"
    then:
      function: pattern
      functionOptions:
        match: "^[A-Z][a-zA-Z0-9 ]*$"

  # All paths must start with /v1/
  paths-versioned:
    description: All paths must include a version prefix (e.g., /v1/).
    severity: error
    given: "$.paths"
    then:
      function: pattern
      functionOptions:
        match: "^/v[0-9]+/"

  # Require tags on all operations
  operation-tags:
    description: All operations must have at least one tag.
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: tags
      function: truthy

  # Require description on all operations
  operation-description:
    description: All operations should have a description.
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: description
      function: truthy

  # Credit authorization specific: POST body must have merchantId
  credit-auth-merchant-id:
    description: Credit authorization operations must include merchantId in the request body.
    severity: warn
    given: "$.paths['/v1/authorizations/*'].post.requestBody.content['application/json'].schema.properties"
    then:
      field: merchantId
      function: truthy

  # Response schemas should be referenced (not inline)
  response-schema-ref:
    description: Response schemas should use $ref references for reusability.
    severity: info
    given: "$.paths[*][*].responses[*].content['application/json'].schema"
    then:
      function: schema
      functionOptions:
        schema:
          oneOf:
            - required:
                - "$ref"
            - type: object

  # Require 400 or 422 responses on POST operations
  post-error-response:
    description: POST operations should include 400 or 422 error responses.
    severity: warn
    given: "$.paths[*].post.responses"
    then:
      function: schema
      functionOptions:
        schema:
          anyOf:
            - required: ["400"]
            - required: ["422"]

  # Require security on all operations
  operation-security:
    description: All operations should declare security requirements.
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: security
      function: truthy

  # Paths must use kebab-case
  paths-kebab-case:
    description: Path segments must use kebab-case.
    severity: warn
    given: "$.paths"
    then:
      function: pattern
      functionOptions:
        match: "^(/[a-z0-9{}-]+)+$"