University of St Andrews · API Governance Rules

University of St Andrews API Rules

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

7 Rules error 2 warn 5

View Rules File View on GitHub

Rule Categories

staandrews

Rules

warn

staandrews-info-contact

API info object should include contact details.

$.info

error

staandrews-server-https

Servers must use HTTPS.

$.servers[*].url

error

staandrews-operation-id

Every operation must declare an operationId.

$.paths[*][get,post,put,delete,patch]

warn

staandrews-snake-case-properties

Response property names follow snake_case, as used across the Sorry status platform.

$.components.schemas[*].properties[*]~

warn

staandrews-timestamps-date-time

created_at and updated_at properties should use date-time format.

$.components.schemas[*].properties[?(@property === 'created_at' || @property === 'updated_at')]

warn

staandrews-collection-meta

Collection responses should expose pagination meta (count, total_count, next_page).

$.components.schemas[?(@property === 'ComponentsResponse' || @property === 'NoticesResponse')].properties

warn

staandrews-state-enum

Component and page state must be constrained to the platform's known values.

$.components.schemas[?(@property === 'Page' || @property === 'Component')].properties.state

Spectral Ruleset

formats:
  - oas3
rules:
  staandrews-info-contact:
    description: API info object should include contact details.
    given: $.info
    severity: warn
    then:
      field: contact
      function: truthy
  staandrews-server-https:
    description: Servers must use HTTPS.
    given: $.servers[*].url
    severity: error
    then:
      function: pattern
      functionOptions:
        match: ^https://
  staandrews-operation-id:
    description: Every operation must declare an operationId.
    given: $.paths[*][get,post,put,delete,patch]
    severity: error
    then:
      field: operationId
      function: truthy
  staandrews-snake-case-properties:
    description: Response property names follow snake_case, as used across the Sorry status platform.
    given: $.components.schemas[*].properties[*]~
    severity: warn
    then:
      function: pattern
      functionOptions:
        match: ^[a-z][a-z0-9_]*$
  staandrews-timestamps-date-time:
    description: created_at and updated_at properties should use date-time format.
    given: $.components.schemas[*].properties[?(@property === 'created_at' || @property === 'updated_at')]
    severity: warn
    then:
      field: format
      function: pattern
      functionOptions:
        match: ^date-time$
  staandrews-collection-meta:
    description: Collection responses should expose pagination meta (count, total_count, next_page).
    given: $.components.schemas[?(@property === 'ComponentsResponse' || @property === 'NoticesResponse')].properties
    severity: warn
    then:
      field: meta
      function: truthy
  staandrews-state-enum:
    description: Component and page state must be constrained to the platform's known values.
    given: $.components.schemas[?(@property === 'Page' || @property === 'Component')].properties.state
    severity: warn
    then:
      field: enum
      function: truthy