ukhsa.oas.rules.yml

extends:
  - ./zalando.oas.rules.yml
  - [spectral:oas, recommended]
  - '@stoplight/spectral-documentation'

documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/

functions:
  - isApiInfoJsonSchema
  - hasRequiredProblemDetailsErrorResponses
  - overrideSeverity

functionsDir: dist/functions

rules:

  # Conditional overrides based on API type
  override-severity-pygeoapi:
    message: "Adjusting severity for pygeoapi definitions"
    documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/severity-overrides/
    given: "$"
    then:
      function: overrideSeverity
      functionOptions:
        target: $.info["x-api-type"]
        value: pygeoapi
        rulesToAdjust:
          must-define-a-format-for-integer-types: warn
          must-define-a-format-for-number-types: warn
          must-define-security-schemes: warn
          must-have-info-api-audience: warn
          must-have-info-contact-email: warn
          must-have-info-value-chain: warn
          must-have-info-version: warn
          must-specify-default-response: warn
          must-use-camel-case-for-property-names: warn
          must-use-camel-case-for-query-parameters: warn
          must-use-https-protocol-only: warn
          must-use-problem-json-as-default-response: warn
          must-use-problem-json-for-errors: warn
          must-use-valid-version-info-schema: warn

  oas3-api-servers: off
  must-have-info-x-api-id: off
  must-always-return-json-objects-as-top-level-data-structures: warn
  should-not-use-api-as-base-path: off

  # MUST Properties must use lower camel case.
  # => /docs/spectral-rules/must/must-use-camel-case-for-property-names.md

  must-use-snake-case-for-property-names: off
  must-use-camel-case-for-property-names:
    given: $.paths.*.*[responses,requestBody]..content..schema..properties.*~
    severity: error
    then:
      function: casing
      functionOptions:
        type: camel
    recommended: true
    description: Properties must use lower camel case.
    message: Properties must use lower camel case.
    documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/must/must-use-camel-case-for-property-names/

  # MUST Query parameters must use lower camel case.
  # => /docs/spectral-rules/must/must-use-camel-case-for-query-parameters.md

  must-use-snake-case-for-query-parameters: off
  must-use-camel-case-for-query-parameters:
    given: $.paths.*.*.parameters[?(@ && @.in=='query')].name
    severity: error
    then:
      function: casing
      functionOptions:
        type: camel
    recommended: true
    description: Query parameters must use lower camel case.
    message: Query parameters must use lower camel case.
    documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/must/must-use-camel-case-for-query-parameters/

  # MUST The `info` object must have an `x-audience` that matches at least one of these values: company-internal, partner-external, premium-external or public-external.
  # => /docs/spectral-rules/must/must-have-info-api-audience.md

  must-provide-api-audience: off
  must-have-info-api-audience:
    given: $.info
    severity: error
    then:
      - function: enumeration
        field: x-audience
        functionOptions:
          values:
            - company-internal
            - partner-external
            - premium-external
            - public-external
      - function: defined
        field: x-audience
    recommended: true
    description: 'The `info` object must have an `x-audience` that matches at least one of these values: company-internal, partner-external, premium-external or public-external.'
    message: Missing or wrong `info.x-audience`, {{error}}.
    documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/must/must-have-info-api-audience/

  # MUST Path must start with a slash and must not end with a slash.
  # => /docs/spectral-rules/must/must-use-normalized-paths.md

  must-use-normalized-paths-without-trailing-slash: off
  must-use-normalized-paths:
    given: $.paths.*~
    severity: error
    then:
      function: pattern
      functionOptions:
        match: ^\/($|[^\/].*[^\/]$)
    description: "Path must start with a slash and must not end with a slash (except root path '/')"
    message: "Path must start with a slash and must not end with a slash (except root path '/')"
    documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/must/must-use-normalized-paths/

  # SHOULD APIs SHOULD have a root path (`/`) defined.
  # => /docs/spectral-rules/must/should-define-api-root.md

  should-define-api-root:
    given: $.paths
    severity: warn
    then:
      field: /
      function: truthy
    recommended: true
    description: Good documentation is always welcome, but API consumers should be able to get a pretty long way through interaction with the API alone. They should at least know they're looking at the right place instead of getting a 404 or random 500 error as is common in some APIs.
    message: APIs SHOULD have a root path (`/`) defined.
    documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/should/should-define-api-root/

  # MUST Root path must define a 200 response..
  # => /docs/spectral-rules/must/must-return-200-for-api-root.md

  must-return-200-for-api-root:
    given: $.paths["/"].*.responses
    severity: error
    then:
      field: '200'
      function: truthy
    recommended: true
    description: 'Root path must define a 200 response.'
    message: 'Root path must define a 200 response.'
    documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/must/must-return-200-for-api-root/

  # MUST `ApiInfo` schema must include this set of minimal required properties and validations.
  # => /docs/spectral-rules/must/must-use-valid-version-info-schema.md

  must-use-valid-version-info-schema:
    given: $.paths["/"].*.responses["200"].content["application/json"]
    severity: error
    then:
      function: isApiInfoJsonSchema
      field: schema
    recommended: true
    description: '`ApiInfo` schema must include this set of minimal required properties and validations.'
    message: '{{error}}'
    documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/must/must-use-valid-version-info-schema/

  # MUST The `info` object must have an `x-value-chain` that matches at least one of these values: prevent, detect, analyse, respond, cross-cutting or enabling.
  # => /docs/spectral-rules/must/must-have-info-value-chain.md

  must-have-info-value-chain:
    given: $.info
    severity: error
    then:
      - function: enumeration
        field: x-value-chain
        functionOptions:
          values:
            - prevent
            - detect
            - analyse
            - respond
            - cross-cutting
            - enabling
      - function: defined
        field: x-value-chain
    recommended: true
    description: 'The `info` object must have an `x-value-chain` that matches at least one of these values: prevent, detect, analyse, respond, cross-cutting or enabling.'
    message: "Missing or wrong `info.x-value-chain`, {{error}}."
    documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/must/must-have-info-value-chain/

  # MUST ALL requests MUST go through `https` protocol only
  # => /docs/spectral-rules/must/must-use-https-protocol-only.md

  must-use-https-protocol-only:
    given: $.servers..url
    severity: error
    then:
      function: pattern
      functionOptions:
        match: "/^https:/"
    recommended: true
    description: ALL requests MUST go through `https` protocol only
    message: Servers MUST be `https` and no other protocol is allowed.
    documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/must/must-use-https-protocol-only/

  # MUST APIs MUST NOT use `HTTP` Basic Authentication.
  # => /docs/spectral-rules/must/must-not-use-http-basic-authentication.md

  must-not-use-http-basic-authentication:
    given: $.components.securitySchemes[*]
    severity: error
    then:
      field: scheme
      function: pattern
      functionOptions:
        notMatch: basic
    recommended: true
    message: APIs MUST NOT use `HTTP` Basic Authentication.
    documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/must/must-not-use-http-basic-authentication/
    description: >-
      HTTP Basic is an inherently insecure way to pass credentials to the API. They're placed in the URL in base64 which can be decrypted easily. Even if you're using a token, there are far better ways to handle passing tokens to an API which are less likely to leak.


      See OWASP advice. https://owasp.org/API-Security/editions/2019/en/0xa2-broken-user-authentication/

  # SHOULD Every request SHOULD support `application/json` media type.
  # => /docs/spectral-rules/should/should-support-application-json-content-request-body.md

  should-support-application-json-content-request-body:
    given: $.paths[*][*].requestBody.content
    severity: warn
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          properties:
            application/json: true
          required:
            - application/json
    recommended: true
    description: Every request SHOULD support at least one `application/json` content type
    message: Every request SHOULD support at least one `application/json` content type.
    documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/should/should-support-application-json-content-request-body/

  # MUST A GET request MUST NOT accept a request body.
  # => /docs/spectral-rules/must/must-not-define-request-body-for-get-requests.md

  must-not-define-request-body-for-get-requests:
    given: $.paths..get.requestBody
    severity: error
    then:
      function: undefined
    recommended: true
    description: Defining a request body on a HTTP GET is in some implementations, but is increasingly frowned upon due to the confusion that comes from unspecified behavior in the HTTP specification.
    message: A GET request MUST NOT accept a request body.
    documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/must/must-not-define-request-body-for-get-requests/

  # MUST All APIs MUST have a security scheme defined.
  # => /docs/spectral-rules/must/must-define-security-schemes.md

  must-define-security-schemes:
    given: $..components
    severity: error
    then:
      field: securitySchemes
      function: truthy
    recommended: true
    description: This API definition does not have any security scheme defined, which means the entire API is open to the public. That's probably not what you want, even if all the data is read-only. Setting lower rate limits for the public and letting known consumers use more resources is a handy path to monetization, and helps know who your power users are when changes need feedback or migration, even if not just good practice.
    message: All APIs MUST have a security scheme defined.
    documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/must/must-define-security-schemes/

  # SHOULD `201 Created` responses to `POST` methods SHOULD have a `Location` header identifying the location of the newly created resource.
  # => /docs/spectral-rules/should/should-have-location-header-in-201-response.md

  should-have-location-header-in-201-response:
    given: $.paths..post.responses["201"]
    severity: warn
    then:
      function: schema
      field: headers
      functionOptions:
        allErrors: true
        schema:
          type: object
          properties:
            Location:
              type: object
              properties:
                description:
                  type: string
                  description: 'The URL of the created resource.'
                schema:
                  type: object
                  properties:
                    type:
                      type: string
                      enum: [string]
                    format:
                      type: string
                      enum: [uri]
                    example:
                      type: string
                  required:
                    - type
                    - format
                    - example
              required:
                - description
                - schema
          required:
            - Location
    recommended: true
    description: '`201 Created` responses to `POST` methods SHOULD have a `Location` header identifying the location of the newly created resource.'
    message: '{{error}}'
    documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/should/should-have-location-header-in-201-response/

  # MUST Each operation MUST define 400, 404, and 500 responses using `application/problem+json` with examples.
  # => /docs/spectral-rules/must/must-define-critical-problem-responses.md

  must-define-critical-problem-responses:
    description: "Operations must define 400, 404, 500 with examples and application/problem+json"
    message: "{{error}}"
    documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/must/must-define-critical-problem-responses/
    severity: warn
    given: $.paths[*][*]
    then:
      function: hasRequiredProblemDetailsErrorResponses
      functionOptions:
        mode: 'critical'

  # MUST Operations with their own non-empty `security` MUST define 401 and 403 responses using `application/problem+json` with examples.
  # => /docs/spectral-rules/must/must-define-security-problem-responses.md

  must-define-security-problem-responses:
    description: "Operations with their own non-empty 'security' MUST define 401 and 403"
    message: "{{error}}"
    documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/must/must-define-security-problem-responses/
    severity: warn
    given: $.paths[*][*]
    then:
      function: hasRequiredProblemDetailsErrorResponses
      functionOptions:
        mode: 'explicit-security'

  # SHOULD include `x-contains-sensitive-data` boolean in the `info` object to indicate presence of sensitive data like PII or PHI.
  # => /docs/spectral-rules/should/should-have-info-x-contains-sensitive-data.md

  should-have-info-x-contains-sensitive-data:
    given: $.info
    severity: warn
    then:
      - function: defined
        field: x-contains-sensitive-data
      - function: schema
        field: x-contains-sensitive-data
        functionOptions:
          schema:
            type: boolean
    recommended: true
    description: 'The `info` object SHOULD contain `x-contains-sensitive-data` to indicate presence of sensitive data such as PII or PHI.'
    message: "Missing or wrong 'info.x-contains-sensitive-data', should be 'boolean'."
    documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/should/should-have-info-x-contains-sensitive-data/

  # MAY include `info.x-api-type` to indicate API category; enforce enum values when present.
  # => /docs/spectral-rules/may/may-have-info-x-api-type.md

  may-have-info-x-api-type:
    given: $.info
    severity: info
    then:
      - function: defined
        field: x-api-type
        message: "info.x-api-type omitted; assuming 'standard'. Valid values: standard, pygeoapi."
      - function: enumeration
        field: x-api-type
        functionOptions:
          values:
            - standard
            - pygeoapi
        message: "info.x-api-type must be one of: standard, pygeoapi. Assuming 'standard' when absent."
    recommended: true
    description: 'APIs MAY include info.x-api-type to indicate API category. When present, it MUST be one of: standard, pygeoapi. When omitted, standard is assumed.'
    message: "Missing or wrong 'info.x-api-type'. Assuming 'standard'. Valid values: standard, pygeoapi."
    documentationUrl: https://ukhsa-collaboration.github.io/standards-org/api-design-guidelines/spectral-rules/may/may-have-info-x-api-type/