Skip to main content

Alpha This is a new service. Help us improve it and give your feedback.

API Design Guidelines

Spectral Rules

Overview

A linting ruleset was created to support API Developers/Providers in achieving the standards described in the UKHSA API Guidelines, ensuring consistency, reliability, and security across all APIs developed within or on behalf of UKHSA.

As well as the rules described herein, the UKHSA ruleset includes the recommended built in spectral OpenAPI Rules and the Spectral Documentation Ruleset; These are common sense rules that ensure an OpenAPI definition adheres to the OpenAPI specification, as well as encourage high quality, rich documentation which is especially important for providing the best possible APIM Developer Portal experience.

Where rules been adopted from from existing open source API rulesets a link is supplied on the relevant rule page.

How to use the rules

Install Spectral

Spectral is a flexible JSON/YAML linter for creating automated style guides, with baked in support for OpenAPI (v3.1, v3.0, and v2.0), Arazzo v1.0, as well as AsyncAPI v2.x.

Install Spectral globally or as a dev dependency.

npm install @stoplight/spectral-cli --save-dev

Read the official spectral documentation for more installation options.

Run Spectral against your OpenAPI definition

Run Spectral against your OpenAPI definition, referencing the spectral ruleset.

You must install the ruleset as via npm package and then reference that, bear in mind the UKHSA ruleset npm package is hosted in github so please read Github’s documentation Installing a GitHub npm package.

npm install @ukhsa-collaboration/spectral-rules --save-dev

create a local .spectral.yml ruleset which extends the one in this repository.

echo "extends: ['@ukhsa-collaboration/spectral-rules']" > .spectral.yml

then you can just run the following.

npx spectral lint openapi-definition.yml

Review and fix any reported issues

Once the linter has highlighted any issues or errors, review and fix to ensure your OpenAPI definition remains compliant with the UKHSA guidelines.

CI/CD Github Actions

The following is a sample Github actions job which can be used as an example of setting up linting as part of you CI/CD pipeline.

...
jobs:
  lint-openapi:
    name: Lint OpenAPI
    runs-on: ubuntu-latest

    permissions:
      contents: read
      issues: read
      checks: write
      pull-requests: write

    steps:
      - name: Checkout code
        uses: actions/checkout@v5

      - uses: actions/setup-node@v4
        with:
          node-version: '22.x'
          registry-url: 'https://npm.pkg.github.com'
          # Defaults to the user or organization that owns the workflow file
          scope: '@ukhsa-collaboration'

      - run: npm install @ukhsa-collaboration/spectral-rules
        env:
          NODE_AUTH_TOKEN: $

      - name: Install spectral
        run: curl -L https://raw.github.com/stoplightio/spectral/master/scripts/install.sh | sh

      - name: Lint example OpenAPI
        run: |
          spectral --version
          spectral lint "*.{json,yml,yaml}" -r $/node_modules/@ukhsa-collaboration/spectral-rules/.spectral.yaml -f github-actions
Tool Description
VS Code Extension Official spectral VS Code extension provides real time linting / intellisense on your OpenAPI definition.
Github Action Official spectral Github action provides ability to lint your OpenAPI definition in CI/CD workflows.

Read the official spectral documentation for more development workflows.

Published: 11 February 2025
Last updated: 19 August 2025
Page Source