apIAddicts · API Governance Rules

apIAddicts API Rules

Spectral linting rules defining API design standards and conventions for apIAddicts.

110 Rules error 87 warn 23
Authorship not recorded No authorship marker is recorded for this file. It is not presented as the provider's; it was most likely written by an API Evangelist pass before outputs were stamped.
View Rules File View on GitHub

Rules

error
apiq:OAR001
For security reasons and as a REST best practice, the HTTPS protocol is mandatory.
$.servers[*].url
error
apiq:OAR002
A wrong scope definition may cause problems to import the API definition into WSO2.
$.x-wso2-security.apim.x-wso2-scopes
error
apiq:OAR003
A description can help other developers to understand the correct use of the scope.
$.x-wso2-security.apim.x-wso2-scopes[*]
error
apiq:OAR004
A role with forbidden characters may cause problems in some applications.
$.x-wso2-security.apim.x-wso2-scopes[*].roles
error
apiq:OAR005
A wrong scope may cause problems to import the API definition into WSO2 or allow all users to call the endpoint.
$
error
apiq:OAR006
Routes must define request media types supported by the API.
$.paths[*][post,put,patch]
error
apiq:OAR007
Routes must define response media types supported by the API
$.paths[*][post,put,patch]$.webhooks[*][post,put,patch]$.paths[*][get,post,put,patch,delete].responses[?(@property != '204')]$.webhooks[*][get,post,put,patch,delete].responses[?(@property != '204')]
error
apiq:OAR008
HTTP verbs not encouraged.
$.paths[*]
error
apiq:OAR009
Default request media type should be defined for operations.
$..content
warn
apiq:OAR010
Default response media type should be defined for responses.
$.paths[*][post,put,patch]$.webhooks[*][post,put,patch]$.paths[*][get,post,put,patch,delete].responses[?(@property != '204')]$.webhooks[*][get,post,put,patch,delete].responses[?(@property != '204')]$.paths[*][get,post,put,patch,delete].responses[?(@property != '204')].content$.webhooks[*][get,post,put,patch,delete].responses[?(@property != '204')].content
error
apiq:OAR011
URLs should follow the configured naming convention (default kebab-case): all literal path segments must comply.
$.paths[*]~$.servers[*].url
warn
apiq:OAR012
Path params, query params, object names and property names should follow the configured naming convention. You can configure snake_case (default), kebab-case, camelCase or UpperCamelCase
$.paths[*][*].parameters[?(@.in == 'path' || @.in == 'query')].name$.paths[*][*].parameters[*].schema.properties.*~$.paths[*][*].requestBody..schema.properties.*~$.paths[*][*].responses..schema.properties.*~$.components.schemas.*~
error
apiq:OAR013
Default response is required for all operations.
$.paths[*][get,post,put,patch,delete].responses
warn
apiq:OAR014
Resources depth level should be below the non-suggested range.
$.paths.*~
error
apiq:OAR015
Resources depth level should be smaller than 5.
$.paths.*~
error
apiq:OAR016
Numeric types requires a valid format.
$..[?(@ && @.type)]
error
apiq:OAR017
Resource path should alternate static and parametrized parts.
$.paths.*~
warn
apiq:OAR018
Operation not recommended for resource path depending on HTTP verb
$.paths
warn
apiq:OAR019
$select must be defined as a query parameter in collection operations (excluding detail endpoints and health checks).
$.paths
warn
apiq:OAR020
$expand must be defined as a query parameter in collection operations (excluding detail endpoints and health checks).
$.paths
warn
apiq:OAR021
$exclude must be defined as a query parameter in collection operations (excluding detail endpoints and health checks).
$.paths
warn
apiq:OAR022
$orderby must be defined as a query parameter in the collection GET operations selected by the configured paths.
$.paths
error
apiq:OAR023
$total must be defined as a query parameter in all collection operations (excluding detail endpoints and health checks).
$.paths[?(!@property.match(/\/me(\/|$)/) && !@property.match(/\/\{[^}]+\}$/) && !@property.match(/status|health|ping/))].get.parameters
error
apiq:OAR024
$start must be defined as a query parameter in all collection operations (excluding detail endpoints and health checks).
$.paths[?(!@property.match(/\/me(\/|$)/) && !@property.match(/\/\{[^}]+\}$/) && !@property.match(/status|health|ping/))].get.parameters
error
apiq:OAR025
$limit must be defined as an integer query parameter in the collection GET operations selected by the configured paths.
$.paths
error
apiq:OAR026
The $total parameter default value should be false.
$.paths[*].get.parameters[?(@.name == '$total' && @.in == 'query')]
error
apiq:OAR027
Location header is required in responses with code 201 from POST operations.
$.paths.*.post.responses['201']
warn
apiq:OAR028
$filter must be defined as a query parameter in the collection GET operations selected by the configured paths.
$.paths
error
apiq:OAR029
A response not compliant with the standard may cause application issues.
$.paths
error
apiq:OAR030
The configured status endpoint must be declared with the configured HTTP method.
$.paths
error
apiq:OAR031
The examples can help developers to understand the response data structure and representation.
$.paths.*.*.parameters.*$.paths.*.*.requestBody$.paths.*.*.responses[?(@property !== "204")]
error
apiq:OAR032
Ambiguous path parts not encouraged.
$.paths.*~
error
apiq:OAR033
Request operation parameters must not include forbidden headers (Accept, Content-Type, Authorization). Note: This validates REQUEST headers, not response headers (see OAR053/114 for response header validation).
$.paths[*][get,post,put,patch,delete].parameters[?(@.in == 'header')]
error
apiq:OAR034
GET collection responses must include a paging block that complies with the standard paging schema (required start, limit and links with self/previous/next; optional numPages and total as integers).
$.paths[*].get.responses[*]
error
apiq:OAR035
Response code 401 must be defined for operations with security schemes defined.
$.paths[*][*]
error
apiq:OAR036
Cookie use is forbidden as a session mechanism.
$.paths[*][get,post,put,patch,delete].parameters[?(@.in == 'header')]$.paths[*][get,post,put,patch,delete].responses[*].headers.*~
error
apiq:OAR037
String schemas must specify a valid format, or a valid pattern when no format is defined.
$..[?(@ && @.type)]
error
apiq:OAR038
The 201 response schema of a POST operation must have properties named 'data' or 'error' with at least one sub-property.
$.paths.*.post.responses['201']
error
apiq:OAR039
Response codes must be defined according to the standard depending on the HTTP verb and resource path.
$.paths[*][*]
error
apiq:OAR040
A scope name non-compliant with the standard may cause problems at application level.
$.x-wso2-security.apim.x-wso2-scopes[*].name
error
apiq:OAR041
A WSO2 x-scope on an operation always requires an x-auth-type definition.
$
error
apiq:OAR042
Base path must be compliant with the standard.
$.basePath$.servers[*].url
error
apiq:OAR043
OpenAPI definition contains structural errors that would be detected by a strict parser or validator.
$.paths.*.*.parameters.*.in$.components.parameters.*.in$.paths.*.*.parameters.*.type$.components.parameters.*.type$.paths.*.*.parameters.*.schema.type$.components.parameters.*.schema.type$.webhooks.*.*.parameters.*.in$.webhooks.*.*.parameters.*.schema.type$.components.pathItems.*.*.parameters.*.in$.components.pathItems.*.*.parameters.*.schema.type
error
apiq:OAR044
Declared media type should conform to RFC6838 and RFC7231.
$.paths.*.*.responses[?(@property !== '204')].content.*~$.paths.*[post,put,patch].requestBody.content.*~$.paths.*.*.parameters[*].content.*~$.paths.*.parameters[*].content.*~$.components.responses.*.content.*~$.components.requestBodies.*.content.*~$.components.parameters.*.content.*~
error
apiq:OAR045
Response schema is required for responses with status codes 201 and others that return content.
$.paths[*][get,post,put,patch,delete].responses[?(@property !== '204')]
error
apiq:OAR046
Each operation SHOULD have a tag.
$.paths[*].get$.paths[*].post$.paths[*].put$.paths[*].patch$.paths[*].delete
error
apiq:OAR047
Tags required and each tag must have a short description, must not be duplicated, and every tag used by an operation must be declared at the top level.
$
error
apiq:OAR048
APIs must define at most one body parameter.
$.paths[*][*]
error
apiq:OAR049
204 No Content MUST NOT return any content.
$.paths[*][get,post,put,patch,delete].responses['204']
error
apiq:OAR050
Provide a summary for each operation.
$.paths[*][get,post,put,patch,delete]
error
apiq:OAR051
Summary and description must be different - not just case variations or semantic duplicates.
$.paths[*][get,post,put,patch,delete]
warn
apiq:OAR052
Numeric schema types must define a format.
$..[?(@ && @.type)]
error
apiq:OAR053
Response headers for API observability and tracing must be defined (excluding 204 responses and health endpoints).
$.paths[*][*].responses[*]
error
apiq:OAR054
Ensure the host matches the specified format
$.servers[*]
error
apiq:OAR060
All query parameters must be defined as optional.
$.paths[*][get,put,post,delete,options,head,patch,trace].parameters[?(@.in == 'query')]$.paths[*].parameters[?(@.in == 'query')]$.components.parameters[?(@.in == 'query')]$.parameters[?(@.in == 'query')]
error
apiq:OAR061
Ensure get have mandatory response codes
$.paths[*][get]
error
apiq:OAR062
Ensure post have mandatory response codes
$.paths[*][post]
error
apiq:OAR063
Ensure put have mandatory response codes
$.paths[*][put]
error
apiq:OAR064
Ensure patch have mandatory response codes
$.paths[*][patch]
error
apiq:OAR065
Ensure delete have mandatory response codes
$.paths[*][delete]
warn
apiq:OAR066
RequestBody and Responses schema property names must be compliant with the snake_case naming convention.
$.paths.*.*[responses,requestBody]..content..schema..properties.*~$.paths.*.*.parameters[?(@.in=='body')].schema..properties.*~$.paths.*.*.responses[*].schema..properties.*~
warn
apiq:OAR067
RequestBody and Responses schema property names must be compliant with the camelCase naming convention.
$.paths.*.*[responses,requestBody]..content..schema..properties.*~
warn
apiq:OAR068
RequestBody and Responses schema property names must be compliant with the PascalCase naming convention.
$.paths.*.*[responses,requestBody]..content..schema..properties.*~
error
apiq:OAR069
Any param in PATH or QUERY should have a Bad Request (400) response.
$.paths
error
apiq:OAR070
Parameters in path should not be numeric.
$.paths[*][get,post,put,patch,delete].parameters[?(@.in == 'path')]
error
apiq:OAR071
Query parameters 'param1', 'param2', and 'param3' must be defined in the operation.
$.paths[*].get.parameters
error
apiq:OAR072
Responses with status codes other than 200 must not include 'stacktrace'.
$.paths[*][get,post,put,patch,delete].responses[?(@property != '200')]
error
apiq:OAR073
API should include a 429 response to indicate rate limiting, except for health check paths like /status, /health, /health-check, /ping, /liveness, /readiness.
$.paths[*][get,post,put,patch,delete]
error
apiq:OAR074
Numeric parameters should define minimum and maximum, or a format restriction.
$..[?(@ && @.in && @.schema && (@.schema.type == 'integer' || @.schema.type == 'number' || (@.schema.type && @.schema.type.indexOf && (@.schema.type.indexOf('integer') > -1 || @.schema.type.indexOf('number') > -1))))].schema$..[?(@ && @.in && (@.type == 'integer' || @.type == 'number' || (@.type && @.type.indexOf && (@.type.indexOf('integer') > -1 || @.type.indexOf('number') > -1))))]
error
apiq:OAR075
String parameters should have minLength, maxLength, pattern (regular expression), or enum restriction.
$.paths[*][*].parameters[*]$.paths[*].parameters[*]$.paths[*].additionalOperations[*].parameters[*]$.webhooks[*][*].parameters[*]$.webhooks[*].parameters[*]$.webhooks[*].additionalOperations[*].parameters[*]$.components.parameters[*]$.parameters[*]
error
apiq:OAR076
Schema should use well-defined type and format.
$..[?(@ && @.type)]
warn
apiq:OAR077
All parameters in query must be snake_case.
$.paths[*][*].parameters[?(@.in == 'query')]$.paths[*].parameters[?(@.in == 'query')]
error
apiq:OAR078
All API methods must have security defined.
$
warn
apiq:OAR079
Operations with path parameters should include a 404 Not Found response.
$.paths[*][get,post,put,patch,delete]
error
apiq:OAR080
The security scheme must be among those allowed by the organization and must be complete.
$.paths[*][get,post,put,patch,delete].security[*]
error
apiq:OAR081
Fields of type password should be string with format password.
$..properties
error
apiq:OAR082
The string properties 'product', 'line', and 'price' must define a byte or binary format.
$..[?(@ && @.properties)]
error
apiq:OAR083
Certain parameters (e.g., email, password) should not pass through the querystring.
$.paths[*][get,post,put,patch,delete].parameters[?(@.in == 'query')]
error
apiq:OAR084
Some formats should not pass through this querystring.
$.paths[*][get,post,put,patch,delete].parameters[?(@.in == 'query')]$.paths[*].parameters[?(@.in == 'query')]
warn
apiq:OAR085
The OpenAPI version must be one of: 2.0, 3.0.0, 3.0.1, 3.0.2, 3.0.3, 3.0.4, 3.1.0, 3.1.1, 3.1.2, 3.2.0.
$.openapi$.swagger
warn
apiq:OAR086
Descriptions must begin with a capital letter, end with a period, and not be empty.
$..description
warn
apiq:OAR087
Summaries must begin with a capital letter, end with a period, and not be empty.
$..summary
warn
apiq:OAR088
The $ref of a parameter must end with the suffix Param.
$..parameters[*].$ref
warn
apiq:OAR089
The $ref of a request body must end with the suffix Body.
$..requestBody.$ref
error
apiq:OAR090
The $ref of a response must end with the suffix Response.
$.paths[*][*].responses[*].$ref
error
apiq:OAR091
Parameters must contain only $ref references.
$.paths[*][get,post,put,patch,delete].parameters[*]
error
apiq:OAR092
RequestBody must contain a $ref.
$.paths[*][get,post,put,patch,delete].requestBody[*].$ref
error
apiq:OAR093
RequestBody must contain only references ($ref).
$.paths[*][get,post,put,patch,delete].responses[*].$ref
warn
apiq:OAR094
Examples must be used instead of example in the content definition for better tool compatibility.
$..content[*].example
error
apiq:OAR096
Response code 403 must be defined for operations with security schemes defined.
$.paths[*][*]
error
apiq:OAR097
The base path must contain at least two parts.
$.servers[*].url
error
apiq:OAR098
The base path must not contain more than two parts.
$.servers[*].url
error
apiq:OAR099
API name must start with prefix 'api-'.
$.servers[*].url$.paths[*]~$.basePath
error
apiq:OAR100
Last path part must be the API version, indicated with the prefix 'v' and the version number as integer.
$.servers[*].url$.basePath
error
apiq:OAR101
The first part of the path should be one of the allowed paths (e.g., '/hello').
$.servers[*].url
error
apiq:OAR102
The second part of the path should be one of the allowed values.
$.servers[*].url
error
apiq:OAR103
GET requests are not recommended for resource paths containing 'get' or 'delete', as this may indicate a design flaw.
$.paths[?(@property.match(/(get|delete)/))].get
error
apiq:OAR104
POST requests should not be used on paths ending with 'me' or a templated parameter.
$.paths[?(/\/(me|{[^}]+})$/.test(@property))].post
error
apiq:OAR105
PUT requests are not recommended for resource paths containing 'get' or 'delete', as this may indicate a design flaw.
$.paths[?(@property.match(/(get|delete)/))].put
error
apiq:OAR106
PATCH requests are not recommended for resource paths containing 'get' or 'delete', as this may indicate a design flaw.
$.paths[?(@property.match(/(get|delete)/))].patch
error
apiq:OAR107
DELETE requests are not recommended for resource paths containing 'get' or 'delete', as this may indicate a design flaw.
$.paths[?(@property.match(/(get|delete)/))].delete
error
apiq:OAR108
The schemas should match the provided examples.
$.paths[*][*].responses[*]
error
apiq:OAR109
Use default response instead of directly specifying 5XX codes.
$.paths[*][get,post,put,patch,delete].responses
error
apiq:OAR110
License information cannot be empty.
$.info
error
apiq:OAR111
Contact information cannot be empty.
$.info
warn
apiq:OAR113
Field or extension must be at the assigned location
$
error
apiq:OAR114
Response headers for API security and key management must be defined (excluding 204 responses).
$.paths[*][*].responses[*]
warn
apiq:OAR115
All fields listed in the required array must be defined in the schema properties.
$..[?(@ && @.required)]
error
apiq:OAR116
Every API path must match the configured regular expression.
$.paths.*~
error
apiq:OAR117
The API title must not match the configured forbidden regular expression.
$.info.title

Spectral Ruleset

Raw ↑ 
# harvested from https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/fba927d25373406a42f384c3905b28dc9d9ad758/apq-spectral.yaml on 2026-10-09 — a Spectral ruleset published in the provider's own GitHub repository (apiaddicts/apiaddicts-style-guide-spectral); found by GitHub code search, fetched verbatim
functionsDir: './functions'
functions:
  - apq-alternate-paths
  - apq-custom-schema
  - apq-compare-insensitive
  - apq-has-filter-query-param
  - apq-parameter-naming-convention
  - apq-resources-by-verb
  - apq-at-most-one-body-parameter
  - apq-standard-response-codes
  - apq-response-headers
  - apq-require-response-on-path-params
  - apq-required-fields-exist
  - apq-response-media-type
  - apq-security-check
  - apq-custom-field
  - apq-check-examples-coverage
  - apq-path-depth
  - apq-forbidden-characters
  - apq-valid-response-schema
  - apq-post-201-location-header
  - apq-response-no-content
  - apq-valid-openapi-version
  - apq-collection-query-param-required
  - apq-total-param-default-value
  - apq-path-param-query-conflict
  - apq-schema-format
  - apq-security-required-response
  - apq-check-ambiguous-path
  - apq-password-format
  - apq-binary-format-check
  - apq-paged-response-check
  - apq-status-endpoint-check
  - apq-validate-structure
  - apq-numeric-parameter-integrity
  - apq-path-pattern
  - apq-query-params-optional
  - apq-wso2-scopes-valid
  - apq-numeric-path-param
  - apq-numeric-invalid-format
  - apq-numeric-missing-format
  - apq-numeric-well-defined-format
  - apq-string-parameter-integrity
  - apq-example-schema-types
  - apq-standard-response-schema
  - apq-allowed-http-verbs
  - apq-url-naming-convention
  - apq-mandatory-response-codes
  - apq-rate-limit-response
  - apq-forbidden-query-format
  - apq-wso2-scope-defined
  - apq-undefined-response-media-type
  - apq-wso2-auth-type-required
  - apq-response-content-required
  - apq-tags-consistency


# --- truncated at 32 KB (51 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/apiaddicts/refs/heads/main/rules/apiaddicts-apiaddicts-style-guide-spectral-spectral-rules.yml

Work with this as data

Every ruleset here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for spectral rules

4 MCP tools reach this
  • find_rulesBrowse and filter every ruleset in the catalog.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This ruleset 
curl "https://apis.io/api/v1/rules/apiaddicts-apiaddicts-style-guide-spectral-spectral-rules"
All spectral rules 
curl "https://apis.io/api/v1/rules?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.