University of Waterloo · API Governance Rules

University of Waterloo API Rules

Spectral linting rules defining API design standards and conventions for University of Waterloo.

5 Rules error 2 warn 2

View Rules File View on GitHub

Rule Categories

Rules

warn

uw-info-title-waterloo

API title should reference Waterloo OpenData.

$.info

error

uw-api-key-security

API uses a custom x-api-key header security scheme.

$.components.securitySchemes

error

uw-paths-versioned-v3

All paths should be under the /v3/ version prefix.

$.paths

hint

uw-operations-read-only

Open data operations are predominantly read-only (GET); flag any non-account write operations for review.

$.paths[?([email protected](/Account/))][put,delete,patch]

warn

uw-schema-no-additional-properties

Response object schemas disallow additionalProperties.

$.components.schemas[*]

Spectral Ruleset

---
# Spectral ruleset encoding observed patterns in the University of Waterloo
# OpenData API (v3). Derived from the live OpenAPI 3.0.4 description at
# https://openapi.data.uwaterloo.ca/swagger/v1/swagger.json
formats:
  - oas3
rules:
  uw-info-title-waterloo:
    description: API title should reference Waterloo OpenData.
    severity: warn
    given: $.info
    then:
      field: title
      function: pattern
      functionOptions:
        match: "(?i)waterloo"

  uw-api-key-security:
    description: API uses a custom x-api-key header security scheme.
    severity: error
    given: $.components.securitySchemes
    then:
      field: apiKey
      function: truthy

  uw-paths-versioned-v3:
    description: All paths should be under the /v3/ version prefix.
    severity: error
    given: $.paths
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          propertyNames:
            pattern: "^/v3/"

  uw-operations-read-only:
    description: >-
      Open data operations are predominantly read-only (GET); flag any
      non-account write operations for review.
    severity: hint
    given: $.paths[?([email protected](/Account/))][put,delete,patch]
    then:
      function: undefined

  uw-schema-no-additional-properties:
    description: Response object schemas disallow additionalProperties.
    severity: warn
    given: $.components.schemas[*]
    then:
      field: additionalProperties
      function: defined