University of Groningen · API Governance Rules

University of Groningen API Rules

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

5 Rules error 1 warn 4

View Rules File View on GitHub

Rule Categories

Rules

warn

ug-info-contact

API info should declare a contact for the providing institution.

$.info

error

ug-servers-https

Server URLs must use HTTPS (UG/DataverseNL endpoints are TLS-only).

$.servers[*].url

warn

ug-operation-tags

Every operation should be tagged so research-information resources stay grouped.

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

warn

ug-uuid-path-params

Pure resource paths identify content items by uuid; uuid path params should be string-typed.

$.paths[*][*].parameters[?(@.name=='uuid')].schema

warn

ug-error-problemdetails

Error responses should reference a structured problem object (Pure ProblemDetails) rather than free text.

$.paths[*][*].responses[?(@property >= '400')].content['application/json'].schema

Spectral Ruleset

formats:
- oas3
rules:
  ug-info-contact:
    description: API info should declare a contact for the providing institution.
    severity: warn
    given: $.info
    then:
      field: contact
      function: truthy
  ug-servers-https:
    description: Server URLs must use HTTPS (UG/DataverseNL endpoints are TLS-only).
    severity: error
    given: $.servers[*].url
    then:
      function: pattern
      functionOptions:
        match: ^https://
  ug-operation-tags:
    description: Every operation should be tagged so research-information resources
      stay grouped.
    severity: warn
    given: $.paths[*][get,put,post,delete]
    then:
      field: tags
      function: truthy
  ug-uuid-path-params:
    description: Pure resource paths identify content items by uuid; uuid path params
      should be string-typed.
    severity: warn
    given: $.paths[*][*].parameters[?(@.name=='uuid')].schema
    then:
      field: type
      function: truthy
  ug-error-problemdetails:
    description: Error responses should reference a structured problem object (Pure
      ProblemDetails) rather than free text.
    severity: warn
    given: $.paths[*][*].responses[?(@property >= '400')].content['application/json'].schema
    then:
      function: truthy