University of Western Australia API Rules

extends: [[spectral:oas, off]]
formats: [oas3]
documentationUrl: https://api.research-repository.uwa.edu.au/ws/api/524/api-docs/documentation/Default.htm
description: >-
  Spectral ruleset encoding conventions observed in the UWA Profiles and
  Research Repository (Elsevier Pure Web Service 524) OpenAPI description.
  These rules reflect real patterns in the converted spec: API-key security
  (query + header), versioned base path, and the WS* schema naming used by Pure.
rules:
  uwa-info-version-present:
    description: Info object must carry the Pure web service version (e.g. 524).
    severity: error
    given: $.info
    then:
      field: version
      function: truthy

  uwa-server-versioned-basepath:
    description: Server URL should target the versioned Pure web service base path /ws/api/<version>.
    severity: warn
    given: $.servers[*].url
    then:
      function: pattern
      functionOptions:
        match: "/ws/api/\\d+$"

  uwa-apikey-security-defined:
    description: An apiKey security scheme must be defined; Pure requires a query or header API key.
    severity: error
    given: $.components.securitySchemes
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          minProperties: 1

  uwa-apikey-scheme-type:
    description: Every declared security scheme should be of type apiKey (Pure does not use OAuth2/HTTP auth on the legacy web service).
    severity: warn
    given: $.components.securitySchemes[*]
    then:
      field: type
      function: pattern
      functionOptions:
        match: "^apiKey$"

  uwa-operation-tagged:
    description: Every operation should be tagged with a Pure resource family (persons, research-outputs, etc.).
    severity: warn
    given: $.paths[*][get,put,post,delete]
    then:
      field: tags
      function: truthy

  uwa-ws-schema-naming:
    description: Pure response/object schemas use the WS prefix (e.g. WSPerson, WSResearchOutput).
    severity: info
    given: $.components.schemas
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          propertyNames:
            pattern: "^WS[A-Z].*$"

  uwa-list-result-envelope:
    description: List-result schemas should expose the standard count + items envelope used across Pure collections.
    severity: info
    given: $.components.schemas[?(@property.match(/ListResult$/))].properties
    then:
      - field: count
        function: truthy
      - field: items
        function: truthy