Tropic API Rules

extends: spectral:oas
rules:
  tropic-operation-summary-title-case:
    description: Operation summaries must use Title Case
    severity: warn
    given: "$.paths[*][*].summary"
    then:
      function: pattern
      functionOptions:
        match: "^([A-Z][a-z]* ?)+$"

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

  tropic-path-versioned:
    description: All paths must be versioned with /v1/ prefix
    severity: warn
    given: "$.paths[*]~"
    then:
      function: pattern
      functionOptions:
        match: "^/v1/"

  tropic-response-success-defined:
    description: All operations must have a 2xx success response
    severity: error
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: responses
      function: schema
      functionOptions:
        schema:
          type: object
          minProperties: 1

  tropic-ids-as-path-params:
    description: Resource IDs should be path parameters named {id}
    severity: hint
    given: "$.paths[*]~"
    then:
      function: pattern
      functionOptions:
        match: "^(/v1/[a-z-]+(/\\{id\\}(/[a-z-]+)?)?)+$"

  tropic-pagination-params:
    description: GET collection endpoints should support page and per_page parameters
    severity: warn
    given: "$.paths[*][get].parameters[*].name"
    then:
      function: enumeration
      functionOptions:
        values:
          - page
          - per_page
          - q
          - status
          - supplier_id

  tropic-request-body-required:
    description: POST and PUT operations must define a requestBody
    severity: error
    given: "$.paths[*][post,put]"
    then:
      field: requestBody
      function: truthy

  tropic-bearer-auth-only:
    description: Only Bearer authentication should be used
    severity: error
    given: "$.components.securitySchemes.*"
    then:
      field: type
      function: enumeration
      functionOptions:
        values:
          - http

  tropic-error-response-shape:
    description: Error responses should include an error field
    severity: warn
    given: "$.paths[*][*].responses[4*,5*].content.application/json.schema.properties"
    then:
      field: error
      function: truthy

  tropic-timestamps-iso8601:
    description: Timestamp fields should use date-time format
    severity: hint
    given: "$.components.schemas[*].properties[created_at,updated_at,approved_at]"
    then:
      field: format
      function: enumeration
      functionOptions:
        values:
          - date-time