University of Edinburgh · API Governance Rules

University of Edinburgh API Rules

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

6 Rules error 2 warn 4

View Rules File View on GitHub

Rule Categories

datashare

Rules

warn

datashare-info-contact

API info should include a contact.

$.info

error

datashare-https-server

Servers must use HTTPS.

$.servers[*].url

warn

datashare-operation-id

Every operation should declare an operationId.

$.paths[*][get]

warn

datashare-object-has-uuid

DSpace object schemas should expose a uuid property.

$.components.schemas[Community,Collection,Item,Bitstream].properties

warn

datashare-uuid-path-params

Resource id path parameters should be typed as uuid strings.

$.components.parameters[communityId,collectionId,itemId,bitstreamId].schema

error

datashare-read-only

Public DataShare REST API is read-only; only GET operations are expected.

$.paths[*]

Spectral Ruleset

extends: [[spectral:oas, off]]
formats:
  - oas3
documentationUrl: https://libraryblogs.is.ed.ac.uk/datablog/2021/12/17/new-feature-in-edinburgh-datashare-the-rest-api/
rules:
  datashare-info-contact:
    description: API info should include a contact.
    severity: warn
    given: $.info
    then:
      field: contact
      function: truthy

  datashare-https-server:
    description: Servers must use HTTPS.
    severity: error
    given: $.servers[*].url
    then:
      function: pattern
      functionOptions:
        match: '^https://'

  datashare-operation-id:
    description: Every operation should declare an operationId.
    severity: warn
    given: $.paths[*][get]
    then:
      field: operationId
      function: truthy

  datashare-object-has-uuid:
    description: DSpace object schemas should expose a uuid property.
    severity: warn
    given: $.components.schemas[Community,Collection,Item,Bitstream].properties
    then:
      field: uuid
      function: defined

  datashare-uuid-path-params:
    description: Resource id path parameters should be typed as uuid strings.
    severity: warn
    given: $.components.parameters[communityId,collectionId,itemId,bitstreamId].schema
    then:
      field: format
      function: pattern
      functionOptions:
        match: '^uuid$'

  datashare-read-only:
    description: Public DataShare REST API is read-only; only GET operations are expected.
    severity: error
    given: $.paths[*]
    then:
      field: post
      function: undefined