Hamad Bin Khalifa University API Rules

# authorship: generated by API Evangelist tooling, 2026-08-30
x-method: generated
# hbku — Spectral ruleset measured from the Fanar API's own conventions.
#
# Rewritten from scratch on 2026-08-30. The previous file in this slot linted the
# Figshare API v2 and asserted that a server URL must be https://api.figshare.com/v2
# — a rule about a vendor's contract, kept under a university's slug.
#
# Provenance (measured against openapi/_original/hbku-fanar-api-openapi.json):
#   - operations carry an operationId: 12/12
#   - operations carry a summary:     12/12
#   - documented error statuses:      14 per operation (400,401,403,404,409,410,413,422,429,499,500,503,504)
#   - security applied document-wide: yes (root `security: [{Bearer: []}]`)
extends: [[spectral:oas, off]]
formats:
  - oas3
rules:
  hbku-info-title-present:
    description: API document must declare an info.title.
    severity: error
    given: $.info
    then:
      field: title
      function: truthy
  hbku-info-version-present:
    description: API document must declare an info.version.
    severity: error
    given: $.info
    then:
      field: version
      function: truthy
  hbku-servers-declared:
    description: >-
      A server URL must be declared. The upstream Fanar document omits servers[] and states the base
      URL only in prose; the working copy in openapi/ repairs that.
    severity: warn
    given: $
    then:
      field: servers
      function: truthy
  hbku-operation-has-operationid:
    description: Every operation should carry an operationId — Fanar does so on all 12.
    severity: error
    given: $.paths[*][get,post,put,patch,delete]
    then:
      field: operationId
      function: truthy
  hbku-operation-has-summary:
    description: Every operation should carry a summary — Fanar does so on all 12.
    severity: warn
    given: $.paths[*][get,post,put,patch,delete]
    then:
      field: summary
      function: truthy
  hbku-operation-documents-401:
    description: >-
      Every operation is authenticated, so every operation should document a 401. This is the
      provider's own convention, not an imported best practice.
    severity: warn
    given: $.paths[*][get,post,put,patch,delete].responses
    then:
      field: '401'
      function: truthy
  hbku-operation-documents-429:
    description: >-
      The API publishes per-model rate limits and a documented 429; operations should say so.
    severity: warn
    given: $.paths[*][get,post,put,patch,delete].responses
    then:
      field: '429'
      function: truthy
  hbku-security-scheme-is-bearer:
    description: Authentication is HTTP bearer; no other scheme is offered.
    severity: warn
    given: $.components.securitySchemes[*]
    then:
      field: scheme
      function: pattern
      functionOptions:
        match: '^bearer$'