UCLouvain · API Governance Rules

UCLouvain API Rules

Spectral linting rules defining API design standards and conventions for UCLouvain.

6 Rules error 3 warn 3
View Rules File View on GitHub

Rule Categories

uclouvain

Rules

error
uclouvain-info-title
API document must declare an info.title.
$.info
error
uclouvain-info-version
API document must declare an info.version (Dataverse release, e.g. 6.8).
$.info
warn
uclouvain-server-defined
At least one server should be defined pointing at the institutional Dataverse /api base.
$.servers
warn
uclouvain-operation-tags
Every operation should carry at least one tag (Dataverse groups operations by resource area).
$.paths[*][get,post,put,delete,patch]
error
uclouvain-operation-responses
Every operation must define at least one response.
$.paths[*][get,post,put,delete,patch]
warn
uclouvain-persistent-id-path-params
Path parameters must be declared (Dataverse paths commonly use {id}, {fileId}, {identifier} for persistent identifiers).
$.paths[*][*].parameters[?(@.in=='path')]

Spectral Ruleset

Raw ↑ 
extends: [[spectral:oas, off]]
formats: [oas3]
documentationUrl: https://guides.dataverse.org/en/latest/api/
rules:
  uclouvain-info-title:
    description: API document must declare an info.title.
    severity: error
    given: $.info
    then:
      field: title
      function: truthy

  uclouvain-info-version:
    description: API document must declare an info.version (Dataverse release, e.g. 6.8).
    severity: error
    given: $.info
    then:
      field: version
      function: truthy

  uclouvain-server-defined:
    description: At least one server should be defined pointing at the institutional Dataverse /api base.
    severity: warn
    given: $.servers
    then:
      function: truthy

  uclouvain-operation-tags:
    description: Every operation should carry at least one tag (Dataverse groups operations by resource area).
    severity: warn
    given: $.paths[*][get,post,put,delete,patch]
    then:
      field: tags
      function: truthy

  uclouvain-operation-responses:
    description: Every operation must define at least one response.
    severity: error
    given: $.paths[*][get,post,put,delete,patch]
    then:
      field: responses
      function: truthy

  uclouvain-persistent-id-path-params:
    description: Path parameters must be declared (Dataverse paths commonly use {id}, {fileId}, {identifier} for persistent identifiers).
    severity: warn
    given: $.paths[*][*].parameters[?(@.in=='path')]
    then:
      field: required
      function: truthy