Imperial College London · API Governance Rules

Imperial College London API Rules

Spectral linting rules defining API design standards and conventions for Imperial College London.

6 Rules error 3 warn 2 info 1

View Rules File View on GitHub

Rule Categories

spiral

Rules

error

spiral-info-version-present

API info must declare a version (DSpace release).

$.info

warn

spiral-server-uses-server-api-base

Servers should use the DSpace /server/api base path.

$.servers[*].url

error

spiral-operations-have-operationid

Every operation must have an operationId.

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

warn

spiral-uuid-path-params-are-uuid-format

Path parameters named uuid must declare format uuid.

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

info

spiral-responses-are-hal-json

200 responses should be served as application/hal+json (DSpace HAL).

$.paths[*][get].responses.200.content

error

spiral-metadata-value-shape

A metadataValue object must always carry a value field.

$.components.schemas.MetadataValue

Spectral Ruleset

formats:
  - oas3
rules:
  spiral-info-version-present:
    description: API info must declare a version (DSpace release).
    severity: error
    given: $.info
    then:
      field: version
      function: truthy
  spiral-server-uses-server-api-base:
    description: Servers should use the DSpace /server/api base path.
    severity: warn
    given: $.servers[*].url
    then:
      function: pattern
      functionOptions:
        match: "/server/api$"
  spiral-operations-have-operationid:
    description: Every operation must have an operationId.
    severity: error
    given: $.paths[*][get,post,put,patch,delete]
    then:
      field: operationId
      function: truthy
  spiral-uuid-path-params-are-uuid-format:
    description: Path parameters named uuid must declare format uuid.
    severity: warn
    given: $.paths[*][*].parameters[?(@.in=='path' && @.name=='uuid')].schema
    then:
      field: format
      function: pattern
      functionOptions:
        match: "^uuid$"
  spiral-responses-are-hal-json:
    description: 200 responses should be served as application/hal+json (DSpace HAL).
    severity: info
    given: $.paths[*][get].responses.200.content
    then:
      field: "application/hal+json"
      function: truthy
  spiral-metadata-value-shape:
    description: A metadataValue object must always carry a value field.
    severity: error
    given: $.components.schemas.MetadataValue
    then:
      field: required
      function: truthy