Skip to main content

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

Spectral Rules

Severity overrides

Some OpenAPI definitions produced by platforms like pygeoapi might struggle to meet every MUST requirement. This is often because these issues are outside the consuming team’s direct control, as fixes would require upstream contributions or maintaining a fork. To accommodate this, as of version 0.4.0 of the ruleset, a custom rule override-severity-pygeoapi has been added to relax the severity of certain rules when an OpenAPI document is identified as being generated by pygeoapi.

The severity of rules is based on the value of an optional openapi extension info.x-api-type in the OpenAPI document.

When an OpenAPI document is marked with info.x-api-type: pygeoapi, the ruleset automatically downgrades the following error-level rules to warn:

  • must-define-a-format-for-integer-types
  • must-define-a-format-for-number-types
  • must-define-security-schemes
  • must-have-info-api-audience
  • must-have-info-contact-email
  • must-have-info-value-chain
  • must-have-info-version
  • must-specify-default-response
  • must-use-camel-case-for-property-names
  • must-use-camel-case-for-query-parameters
  • must-use-https-protocol-only
  • must-use-problem-json-as-default-response
  • must-use-problem-json-for-errors
  • must-use-valid-version-info-schema

Other rules continue to run normally, so pygeoapi definitions should still be linted and improved where possible. Rules already at warn are not changed.

Important:

These overrides apply to the whole OpenAPI definition, even if it is possible the developer can modify the output of pygeoapi and fix the issues so be sure to review the reported warnings and errors carefully and fix where possible.

To make intent explicit, the info.x-api-type field can be treated as an enum in API definitions to indicate the API category:

  • standard – default behavior; no overrides applied.
  • pygeoapi – pygeoapi-based definitions; specific error-level rules listed above are downgraded to warn.

If you omit info.x-api-type, the ruleset assumes the API is standard.

See also: MAY have info.x-api-type.

When generating a definition from a local pygeoapi instance, you can inject the info.x-api-type flag during export so relaxed severities will be applied. The example below wraps the pygeoapi openapi generate command in Docker, binds your local configuration, and uses yq to add info.x-api-type: pygeoapi before writing the result to openapi-pygeoapi.yml.

docker run --entrypoint= --rm -p 5000:80 \
  --mount type=bind,src=./pygeoapi-config.yml,dst=/pygeoapi/config.yml \
  -e PYGEOAPI_CONFIG=/pygeoapi/config.yml geopython/pygeoapi:latest \
  sh -c 'pygeoapi openapi generate $PYGEOAPI_CONFIG'  \
| yq '.info += {"x-api-type": "pygeoapi"}' - > openapi-pygeoapi.yml

Published: 5 November 2025
Last updated: 5 November 2025
Page Source