extends: [[spectral:oas, all]]
documentationUrl: https://developer.paychex.com/
rules:
  paychex-info-contact-required:
    description: Paychex APIs must publish a developer-program contact in info.contact.
    severity: error
    given: $.info
    then:
      field: contact
      function: truthy
  paychex-server-https:
    description: All Paychex API servers must use HTTPS and point at api.paychex.com.
    severity: error
    given: $.servers[*].url
    then:
      function: pattern
      functionOptions:
        match: "^https://api\\.paychex\\.com.*"
  paychex-security-oauth2-required:
    description: Paychex APIs must declare an OAuth 2.0 client_credentials security scheme.
    severity: error
    given: $.components.securitySchemes
    then:
      function: truthy
  paychex-tags-title-case:
    description: OpenAPI tag names must use Title Case (e.g., Time Entries, not time_entries).
    severity: warn
    given: $.tags[*].name
    then:
      function: pattern
      functionOptions:
        match: "^[A-Z][A-Za-z0-9]*( [A-Z][A-Za-z0-9]*)*$"
  paychex-operation-id-camel-case:
    description: operationId must be camelCase and start with a verb.
    severity: warn
    given: $.paths.*.*.operationId
    then:
      function: pattern
      functionOptions:
        match: "^(list|get|create|update|delete|submit|cancel|approve)[A-Z][A-Za-z0-9]*$"
  paychex-operation-summary-title-case:
    description: Operation summaries should be in Title Case.
    severity: warn
    given: $.paths.*.*.summary
    then:
      function: pattern
      functionOptions:
        match: "^([A-Z][A-Za-z0-9'-]*)([ /-][A-Za-z0-9'-]+)*$"
  paychex-list-pagination:
    description: GET list operations should expose offset and limit query parameters.
    severity: warn
    given: $.paths[?(@property.match(/^\\/companies($|\\/[^\\/]+\\/(workers))$/))].get
    then:
      field: parameters
      function: truthy
  paychex-error-401-defined:
    description: Every operation must define a 401 response for invalid OAuth tokens.
    severity: error
    given: $.paths.*.*.responses
    then:
      field: "401"
      function: truthy
  paychex-error-429-defined:
    description: Every operation must define a 429 response for rate-limited callers.
    severity: warn
    given: $.paths.*.*.responses
    then:
      field: "429"
      function: truthy