National University of Singapore · API Governance Rules

National University of Singapore API Rules

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

6 Rules error 2 warn 4

View Rules File View on GitHub

Rule Categories

nus

Rules

warn

nus-info-contact-or-description

API info should carry a description so consumers understand the NUSMods data scope.

$.info

warn

nus-server-https

Prefer the HTTPS NUSMods server entry.

$.servers[*].url

error

nus-paths-end-in-json

All NUSMods resources are static JSON files; every path must end in .json (observed convention).

$.paths[*]~

error

nus-get-only

NUSMods data is read-only; only GET operations are expected.

$.paths[*][?(@property != 'get' && @property != 'summary' && @property != 'parameters' && @property != 'description')]~

warn

nus-acadyear-path-param

Year-scoped resources should declare the acadYear path parameter.

$.paths[?(@property.match(/{acadYear}/))][get].parameters

warn

nus-module-code-string

moduleCode is always a string identifier (e.g. CS2100).

$.components.schemas[*].properties.moduleCode

Spectral Ruleset

rules:
  nus-info-contact-or-description:
    description: API info should carry a description so consumers understand the NUSMods data scope.
    severity: warn
    given: $.info
    then:
      field: description
      function: truthy

  nus-server-https:
    description: Prefer the HTTPS NUSMods server entry.
    severity: warn
    given: $.servers[*].url
    then:
      function: pattern
      functionOptions:
        match: "^https://"

  nus-paths-end-in-json:
    description: All NUSMods resources are static JSON files; every path must end in .json (observed convention).
    severity: error
    given: $.paths[*]~
    then:
      function: pattern
      functionOptions:
        match: "\\.json$"

  nus-get-only:
    description: NUSMods data is read-only; only GET operations are expected.
    severity: error
    given: $.paths[*][?(@property != 'get' && @property != 'summary' && @property != 'parameters' && @property != 'description')]~
    then:
      function: falsy

  nus-acadyear-path-param:
    description: Year-scoped resources should declare the acadYear path parameter.
    severity: warn
    given: $.paths[?(@property.match(/{acadYear}/))][get].parameters
    then:
      function: truthy

  nus-module-code-string:
    description: moduleCode is always a string identifier (e.g. CS2100).
    severity: warn
    given: $.components.schemas[*].properties.moduleCode
    then:
      field: type
      function: pattern
      functionOptions:
        match: "^string$"