Uppsala University · API Governance Rules

Uppsala University API Rules

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

7 Rules error 3 warn 4
View Rules File View on GitHub

Rule Categories

ucdp

Rules

warn
ucdp-info-contact
API info should include a contact pointing to the UCDP docs.
$.info
error
ucdp-server-defined
A server URL must be defined (UCDP base is ucdpapi.pcr.uu.se).
$.servers
error
ucdp-version-path-param
Dataset paths are versioned and require a required {version} path parameter.
$.paths[?(@property.match(/\/api\//))].get.parameters[?(@.name == 'version')]
warn
ucdp-pagination-params
Dataset operations should expose pagesize and page query parameters.
$.paths[?(@property.match(/\/api\//))].get
error
ucdp-api-token-security
A header API token security scheme (x-ucdp-access-token) must be declared.
$.components.securitySchemes
warn
ucdp-response-envelope
Successful responses should use a paginated envelope (TotalCount, Result).
$.components.schemas[?(@property.match(/APIResponse$/))].properties
warn
ucdp-json-media-type
Operations should advertise an application/json response.
$.paths[?(@property.match(/\/api\//))].get.responses.200.content

Spectral Ruleset

Raw ↑ 
---
# Spectral ruleset encoding observed patterns in the UCDP Public API.
# Patterns are derived from the real OpenAPI 3.0 description at
# https://ucdpapi.pcr.uu.se/swagger/v1/swagger.json
formats:
  - oas3
extends:
  - spectral:oas
rules:
  ucdp-info-contact:
    description: API info should include a contact pointing to the UCDP docs.
    given: $.info
    severity: warn
    then:
      field: contact
      function: truthy

  ucdp-server-defined:
    description: A server URL must be defined (UCDP base is ucdpapi.pcr.uu.se).
    given: $.servers
    severity: error
    then:
      function: length
      functionOptions:
        min: 1

  ucdp-version-path-param:
    description: Dataset paths are versioned and require a required {version} path parameter.
    given: $.paths[?(@property.match(/\/api\//))].get.parameters[?(@.name == 'version')]
    severity: error
    then:
      field: required
      function: truthy

  ucdp-pagination-params:
    description: Dataset operations should expose pagesize and page query parameters.
    given: $.paths[?(@property.match(/\/api\//))].get
    severity: warn
    then:
      field: parameters
      function: truthy

  ucdp-api-token-security:
    description: A header API token security scheme (x-ucdp-access-token) must be declared.
    given: $.components.securitySchemes
    severity: error
    then:
      field: ApiToken
      function: truthy

  ucdp-response-envelope:
    description: Successful responses should use a paginated envelope (TotalCount, Result).
    given: $.components.schemas[?(@property.match(/APIResponse$/))].properties
    severity: warn
    then:
      field: Result
      function: truthy

  ucdp-json-media-type:
    description: Operations should advertise an application/json response.
    given: $.paths[?(@property.match(/\/api\//))].get.responses.200.content
    severity: warn
    then:
      field: application/json
      function: truthy