Maastricht University · API Governance Rules

Maastricht University API Rules

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

7 Rules error 3 warn 3 info 1
View Rules File View on GitHub

Rule Categories

maastricht

Rules

error
maastricht-info-title
API info.title must be present and reference the Dataverse API.
$.info
error
maastricht-info-version
API must declare a version (DataverseNL runs Dataverse 6.x).
$.info
warn
maastricht-servers-defined
A servers array should be present so consumers can resolve the DataverseNL base URL.
$
warn
maastricht-server-is-dataversenl
At least one server should point at the DataverseNL host.
$.servers[*].url
info
maastricht-paths-lowercase-api
Dataverse REST paths are namespaced under /access, /admin, /dataverses, /datasets, /search, /info.
$.paths[*]~
warn
maastricht-operation-has-tags
Each operation should carry at least one tag for grouping (Dataverse tags every operation).
$.paths[*][get,put,post,delete,patch]
error
maastricht-operation-has-responses
Each operation must define responses.
$.paths[*][get,put,post,delete,patch]

Spectral Ruleset

Raw ↑ 
formats: [oas3]
documentationUrl: https://guides.dataverse.org/en/latest/api/
description: >-
  Spectral ruleset encoding patterns observed in the DataverseNL (Maastricht University
  collection) OpenAPI 3.0.3 description retrieved live from https://dataverse.nl/openapi.
rules:
  maastricht-info-title:
    description: API info.title must be present and reference the Dataverse API.
    severity: error
    given: $.info
    then:
      field: title
      function: truthy

  maastricht-info-version:
    description: API must declare a version (DataverseNL runs Dataverse 6.x).
    severity: error
    given: $.info
    then:
      field: version
      function: truthy

  maastricht-servers-defined:
    description: A servers array should be present so consumers can resolve the DataverseNL base URL.
    severity: warn
    given: $
    then:
      field: servers
      function: truthy

  maastricht-server-is-dataversenl:
    description: At least one server should point at the DataverseNL host.
    severity: warn
    given: $.servers[*].url
    then:
      function: pattern
      functionOptions:
        match: "dataverse\\.nl"

  maastricht-paths-lowercase-api:
    description: Dataverse REST paths are namespaced under /access, /admin, /dataverses, /datasets, /search, /info.
    severity: info
    given: $.paths[*]~
    then:
      function: pattern
      functionOptions:
        match: "^/"

  maastricht-operation-has-tags:
    description: Each operation should carry at least one tag for grouping (Dataverse tags every operation).
    severity: warn
    given: $.paths[*][get,put,post,delete,patch]
    then:
      field: tags
      function: truthy

  maastricht-operation-has-responses:
    description: Each operation must define responses.
    severity: error
    given: $.paths[*][get,put,post,delete,patch]
    then:
      field: responses
      function: truthy