McGill University · API Governance Rules

McGill University API Rules

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

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

Rule Categories

mcgill

Rules

error
mcgill-info-title-present
API document must declare a title.
$.info
error
mcgill-info-version-present
API document must declare a version (mirrors the Dataverse build version).
$.info
error
mcgill-server-is-borealis
The server URL must be the Borealis Dataverse API base hosting the McGill collection.
$.servers[*]
warn
mcgill-operation-id-present
Every operation should carry the upstream Dataverse operationId.
$.paths[*][get,post,put,delete]
warn
mcgill-operation-tagged
Every operation should be tagged (dataverses, search, info).
$.paths[*][get,post,put,delete]
warn
mcgill-json-responses-only
Public Dataverse responses are JSON; documented 200 responses must offer application/json.
$.paths[*][get,post,put,delete].responses.200.content
warn
mcgill-envelope-status-field
Response envelope schema must expose the Dataverse 'status' field.
$.components.schemas.ApiResponse.properties

Spectral Ruleset

Raw ↑ 
extends: [[spectral:oas, off]]
formats: [oas3]
documentationUrl: https://borealisdata.ca/guides/en/latest/api/native-api.html
rules:
  mcgill-info-title-present:
    description: API document must declare a title.
    given: $.info
    severity: error
    then:
      field: title
      function: truthy
  mcgill-info-version-present:
    description: API document must declare a version (mirrors the Dataverse build version).
    given: $.info
    severity: error
    then:
      field: version
      function: truthy
  mcgill-server-is-borealis:
    description: The server URL must be the Borealis Dataverse API base hosting the McGill collection.
    given: $.servers[*]
    severity: error
    then:
      field: url
      function: pattern
      functionOptions:
        match: "^https://borealisdata\\.ca/api"
  mcgill-operation-id-present:
    description: Every operation should carry the upstream Dataverse operationId.
    given: $.paths[*][get,post,put,delete]
    severity: warn
    then:
      field: operationId
      function: truthy
  mcgill-operation-tagged:
    description: Every operation should be tagged (dataverses, search, info).
    given: $.paths[*][get,post,put,delete]
    severity: warn
    then:
      field: tags
      function: truthy
  mcgill-json-responses-only:
    description: Public Dataverse responses are JSON; documented 200 responses must offer application/json.
    given: $.paths[*][get,post,put,delete].responses.200.content
    severity: warn
    then:
      field: application/json
      function: truthy
  mcgill-envelope-status-field:
    description: Response envelope schema must expose the Dataverse 'status' field.
    given: $.components.schemas.ApiResponse.properties
    severity: warn
    then:
      field: status
      function: truthy