extends: []
formats:
  - oas3
documentationUrl: https://librarycatalogue.taylors.edu.my/api/v1/
rules:
  taylors-info-contact:
    description: API info object should declare a contact for the Taylor's Library.
    severity: warn
    given: $.info
    then:
      field: contact
      function: truthy
  taylors-server-https:
    description: Servers must use HTTPS (Koha catalog is served over TLS).
    severity: error
    given: $.servers[*].url
    then:
      function: pattern
      functionOptions:
        match: "^https://"
  taylors-operation-id:
    description: Every operation should declare an operationId.
    severity: error
    given: $.paths[*][get,post,put,patch,delete]
    then:
      field: operationId
      function: truthy
  taylors-operation-tags:
    description: Every operation should be tagged with its Koha resource collection.
    severity: warn
    given: $.paths[*][get,post,put,patch,delete]
    then:
      field: tags
      function: truthy
  taylors-snake-case-properties:
    description: >-
      Koha REST API object properties use snake_case identifiers
      (e.g. patron_id, checkout_date, library_id).
    severity: warn
    given: $.components.schemas[*].properties.*~
    then:
      function: pattern
      functionOptions:
        match: "^[a-z][a-z0-9_]*$"
  taylors-id-suffix-integer:
    description: >-
      Internal resource identifiers ending in _id (patron_id, item_id,
      checkout_id, hold_id, biblio_id) are integers.
    severity: info
    given: $.components.schemas[*].properties[?(@property.match(/^(patron|item|checkout|hold|biblio)_id$/))]
    then:
      field: type
      function: pattern
      functionOptions:
        match: "integer"
  taylors-auth-required:
    description: >-
      Patron and circulation collection endpoints must document a 401
      Unauthorized response (anonymous access is rejected).
    severity: warn
    given: $.paths[*][get,post,put,patch,delete].responses
    then:
      field: "401"
      function: truthy