Define & Validate APIsValidation RulesetsOpenAPI Rulesets
OpenAPI v3 Standard Validation
Validation checks performed on provided OpenAPI v3 file to check its conformance to rules set by the OpenAPI v3 official standards document.
| Property | Value |
|---|---|
| Ruleset ID | openapi-v3-standards-validation |
| Code prefix | OPENAPI3STANDARDS_V |
| Type | Validation |
| Default severity | Error |
| Rule system | Semantic |
| Rules | 155 |
Rules marked (disabled) are turned off by default, so they don't report issues.
OpenAPI Root Information
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3STANDARDS_V001 | required-openapi-version | Blocking | The OpenAPI specification's root object must specify the openapi property to indicate the version of the OpenAPI standard document you are using to define your specification. |
OPENAPI3STANDARDS_V002 | valid-openapi-version | Error | Your OpenAPI specification's root object must specify a valid OpenAPI standard document version using the openapi property. The value must be a valid semantic version number of the OpenAPI standard document in the 3.0.n or 3.1.n range e.g. 3.0.3, 3.1.0, etc. |
OPENAPI3STANDARDS_V003 | required-api-info | Error | The OpenAPI root object must specify metadata about the API using the info property. |
OPENAPI3STANDARDS_V004 | required-paths | Error | The OpenAPI root object in an OpenAPI v3.0.x document must specify the available paths and operations for the API using the paths property. |
OPENAPI3STANDARDS_V005 | required-paths-or-components-or-webhooks | Error | The OpenAPI root object in an OpenAPI v3.1.x document must specify at least one of the following: available paths and operations for the API using the paths property OR reusable components using the components property OR information about incoming webhooks using the webhooks property. |
OPENAPI3STANDARDS_V006 | unique-webhooks-key | Error | The key name assigned to the entries in the OpenAPI Object webhooks map must be a unique string to refer to each webhook. |
Info
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3STANDARDS_V010 | required-info-title | Error | The Info Object must specify a title of the API using the title property. |
OPENAPI3STANDARDS_V011 | required-info-version | Error | The Info Object must specify a version number for the current API specification document using the version property. |
License
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3STANDARDS_V020 | required-license-name | Error | The License Object must specify name of the license (used for the API) using the name property. |
OPENAPI3STANDARDS_V021 | license-identifier-and-url-are-mutually-exclusive | Warning | The properties identifier and url in License Object are mutually exclusive. This means that in a License Object instance, only one of these properties must be present at a time but not both. |
Servers
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3STANDARDS_V025 | required-server-url | Error | The Server Object must specify a URL for the target API host using the url property. |
Server Variables
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3STANDARDS_V030 | required-server-variable-default-value | Error | The Server Variable Object must specify a default value for the variable using the 'default' property that can be substituted in the server URL in case no other value is supplied at the time of making the request. If the default value is not provided, a dummy value will be assigned automatically during import/transformations in APIMatic. |
OPENAPI3STANDARDS_V031 | at-least-one-item-in-server-variable-enum-list | Error | If an enumeration list is declared using the enum property it must contain at least one string-valued entry which can be used for substitution i.e. the enumeration array must not be empty. |
OPENAPI3STANDARDS_V032 | valid-server-variable-default-value-for-enum | Error | If a default value is provided for the server variable and an enumeration list is also defined using the enum property, the default value must exist in this list. |
Paths
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3STANDARDS_V035 | unique-path | Error | Path keys are patterned fields that must have unique values within the Paths Object. |
OPENAPI3STANDARDS_V036 | pre-defined-path-parameter-for-path-url-template-expression | Error | A path parameter referenced in the path URL must be defined within every Operation Object associated with the Path Item Object, or defined once globally in the Path Item Object parameters. An exception is if the path item is empty, for example due to ACL constraints, matching path parameters are not required. |
OPENAPI3STANDARDS_V037 | non-identical-templated-paths | Error | When matching URLs, concrete (non-templated) paths are matched before their templated counterparts. Templated paths with the same hierarchy but different templated names must not exist as they are considered identical. |
Path Items
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3STANDARDS_V045 | path-item-reference-is-a-path-item-object | Error | When $ref is used within a Path Item Object, it must point to a valid Path Item Object defined elsewhere and which will replace the current Path Item Object with its contents. The $ref must eventually resolve into a Path Item Object (and no other type of object). The resolved object should not contain $ref as a property i.e. the references must not form an endless loop. |
OPENAPI3STANDARDS_V046 | unique-path-item-parameter | Error | The parameters list provided using the parameters property in the Path Item Object must not include any duplicate parameter definitions. A unique parameter is defined by a combination of its name and location. |
Operations
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3STANDARDS_V050 | required-operation-responses | Error | The Operation Object in an OpenAPI v3.0.x document must specify list of possible responses that can be returned from executing this operation, using the responses property. |
OPENAPI3STANDARDS_V051 | unique-operation-id | Error | The id specified in the Operation Object using the operationId property must be unique among all operations described in the current API specification document. |
OPENAPI3STANDARDS_V052 | unique-operation-parameter | Error | The parameters list provided using the parameters property in the Operation Object must not include any duplicate parameter definitions. A unique parameter is defined by a combination of its name and location. |
OPENAPI3STANDARDS_V053 | get-operation-cannot-have-request-body | Warning | HTTP methods like GET, DELETE, HEAD are not allowed to have a request body since a payload for these methods do not have any defined semantics. If request body is defined for non-body HTTP verbs, it will get ignored automatically during import/transformations in APIMatic. Therefore, in OpenAPI as well, the GET Operation Object must not set the requestBody property. |
OPENAPI3STANDARDS_V054 | delete-operation-cannot-have-request-body | Warning | HTTP methods like GET, DELETE, HEAD are not allowed to have a request body since a payload for these methods do not have any defined semantics. If request body is defined for non-body HTTP verbs, it will get ignored. Therefore, in OpenAPI as well, the DELETE Operation Object must not set the requestBody property. |
OPENAPI3STANDARDS_V055 | head-operation-cannot-have-request-body | Warning | HTTP methods like GET, DELETE, HEAD are not allowed to have a request body since a payload for these methods do not have any defined semantics. If request body is defined for non-body HTTP verbs, it will get ignored. Therefore, in OpenAPI as well, the HEAD Operation Object must not set the requestBody property. |
OPENAPI3STANDARDS_V056 | unique-operation-callback-key | Error | The key of the Operation Object level callbacks map must be a unique identifier for the Callback Object. |
External Documentation
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3STANDARDS_V070 | required-external-documentation-url | Error | The External Documentation Object must specify the URL for the target documentation using the url property. |
Parameters
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3STANDARDS_V075 | required-parameter-name | Error | The Parameter Object must specify a name for the parameter using the name property. The name is API/service defined and must not be null or empty. |
OPENAPI3STANDARDS_V076 | required-parameter-location | Error | The Parameter Object must specify a location for the parameter using the in property. The location identifies where the parameter needs to be sent in the request and must not be null or empty. Possible values are 'query', 'header', 'path' or 'cookie'. |
OPENAPI3STANDARDS_V077 | required-parameter-schema-or-content | Error | The Parameter Object must define the type schema for the parameter using either the schema or content property. The former is used more commonly while the latter is recommended for more complex scenarios involving media types. However, at one time, only one of these properties must be present and not both. |
OPENAPI3STANDARDS_V078 | parameter-schema-and-content-are-mutually-exclusive | Error | The properties schema and content in Parameter Object are mutually exclusive. This means that in a Parameter Object instance, only one of these properties must be present at a time but not both. |
OPENAPI3STANDARDS_V079 | valid-parameter-location | Error | Location of a parameter specified using the in property in the Parameter Object must have one of the following possible values only: query, header, path or cookie. All other values will be treated as invalid. |
OPENAPI3STANDARDS_V080 | path-parameter-exists-in-path-url-template | Error | If a parameter is defined in the parameters list with location set as path, a corresponding URL segment in the path URL must exist for that parameter. A path URL can use curly braces ({}) to mark a section of a URL path as replaceable with a path parameter value. The name specified within these braces must match exactly with the name of the path parameter defined in the parameters list. |
OPENAPI3STANDARDS_V081 | required-path-parameter-required-attribute | Error | If the Parameter Object location is set to path it must specify the property required with value set to true. |
OPENAPI3STANDARDS_V082 | path-parameter-cannot-be-optional | Error | If the location is set as path, the parameter must be set as required using the property required of the Parameter Object. The value of this property must be set to true. |
OPENAPI3STANDARDS_V083 | no-accept-header-parameter-definition | Warning | The parameters list must not contain an explicit definition for the Accept header parameter. If a definition is added, it will be ignored. |
OPENAPI3STANDARDS_V084 | no-content-type-header-parameter-definition | Warning | The parameters list must not contain an explicit definition for the Content-Type header parameter. If a definition is added, it will be ignored. |
OPENAPI3STANDARDS_V085 | no-authorization-header-parameter-definition | Warning | The parameters list must not contain an explicit definition for the Authorization header parameter. If a definition is added, it will be ignored. |
OPENAPI3STANDARDS_V086 | valid-parameter-style | Error | The property style in a Parameter Object can have only one of the following possible values: matrix, label, form, simple, spaceDelimited, pipeDelimited or deepObject. All other values will be treated as invalid. |
OPENAPI3STANDARDS_V087 | valid-query-parameter-style | Error | For query parameters, only the following styles are applicable: form, spaceDelimited, pipeDelimited or deepObject. Rest will be treated as invalid. |
OPENAPI3STANDARDS_V088 | valid-path-parameter-style | Error | For path parameters, only the following styles are applicable: matrix, label, or simple. Rest will be treated as invalid. |
OPENAPI3STANDARDS_V089 | valid-header-parameter-style | Error | For header parameters, only the simple style is applicable and rest will be treated as invalid. |
OPENAPI3STANDARDS_V090 | valid-cookie-parameter-style | Error | For cookie parameters, only the form style is applicable and rest will be treated as invalid. |
OPENAPI3STANDARDS_V091 | parameter-simple-style-only-for-array-type | Error | The simple style can only be used when the type of the parameter is set as array i.e. it cannot be used for primitive or object types. |
OPENAPI3STANDARDS_V092 | parameter-space-delimited-style-only-for-array-type | Error | In an OpenAPI v3.0.x document, the spaceDelimited style can only be used when the type of the parameter is set as array i.e. it cannot be used for primitive or object types. |
OPENAPI3STANDARDS_V093 | parameter-pipe-delimited-style-only-for-array-type | Error | In an OpenAPI v3.0.x document, the pipeDelimited style can only be used when the type of the parameter is set as array i.e. it cannot be used for primitive or object types. |
OPENAPI3STANDARDS_V094 | parameter-deep-object-style-only-for-object-type | Error | The deepObject style can only be used when the type of the parameter is set as object i.e. it cannot be used for primitive or array types. |
OPENAPI3STANDARDS_V095 | no-allow-empty-value-for-simple-style-parameter | Warning | Empty valued parameters cannot be serialized when using the simple style type. Therefore, for such cases, the value of allowEmptyValue will be ignored. |
OPENAPI3STANDARDS_V096 | no-allow-empty-value-for-space-delimited-style-parameter | Warning | Empty valued parameters cannot be serialized when using the spaceDelimited style type. Therefore, for such cases, the value of allowEmptyValue will be ignored. |
OPENAPI3STANDARDS_V097 | no-allow-empty-value-for-pipe-delimited-style-parameter | Warning | Empty valued parameters cannot be serialized when using the pipeDelimited style type. Therefore, for such cases, the value of allowEmptyValue will be ignored. |
OPENAPI3STANDARDS_V098 | no-allow-empty-value-for-deep-object-style-parameter | Warning | Empty valued parameters cannot be serialized when using the deepObject style type. Therefore, for such cases, the value of allowEmptyValue will be ignored. |
OPENAPI3STANDARDS_V099 | parameter-example-and-examples-are-mutually-exclusive | Warning | The properties example and examples in Parameter Object are mutually exclusive. This means that in a Parameter Object instance, only one of these properties must be present at a time but not both. |
OPENAPI3STANDARDS_V100 | parameter-example-overrides-schema-example | Information | An example for a parameter can be provided in multiple ways: either directly in the Parameter Object using the examples/example property or within the parameter level schema definition using the example property. If an example is provided at both levels, the Parameter Object level example will override the Schema Object level example. |
OPENAPI3STANDARDS_V101 | parameter-examples-override-schema-example | Information | An example for a parameter can be provided in multiple ways: either directly in the Parameter Object using the examples/example property or within the parameter level schema definition using the example property. If an example is provided at both levels, the Parameter Object level examples will override the Schema Object level example. |
OPENAPI3STANDARDS_V102 | single-entry-parameter-content-map | Error | The content property of the Parameter Object is a map that contains representations of the parameter such that the key represents the media type while the value describes the parameter schema. This content map must contain only one entry. |
OPENAPI3STANDARDS_V103 | parameter-space-delimited-style-only-for-array-or-object-types | Error | In an OpenAPI v3.1.x document, the spaceDelimited style can only be used when the type of the parameter is set as array or object i.e. it cannot be used for primitive types. |
OPENAPI3STANDARDS_V104 | parameter-pipe-delimited-style-only-for-array-or-object-types | Error | In an OpenAPI v3.1.x document, the pipeDelimited style can only be used when the type of the parameter is set as array or object i.e. it cannot be used for primitive types. |
Request Body
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3STANDARDS_V120 | required-request-body-content | Error | The Request Body Object must define the request body content using the content property. |
OPENAPI3STANDARDS_V121 | multipart-media-type-for-multi-file-request-body | Error | To upload multiple files, a multipart media type must be used in the request body definition. |
Media Types
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3STANDARDS_V130 | required-media-type-schema-for-multipart-request-body | Error | The request body multipart media type definition must contain a schema property to define the input parameters to the operation. |
OPENAPI3STANDARDS_V131 | media-type-example-and-examples-are-mutually-exclusive | Warning | The properties example and examples in Media Type Object are mutually exclusive. This means that in a Media Type Object instance, only one of these properties must be present at a time but not both. |
OPENAPI3STANDARDS_V132 | media-type-example-overrides-media-schema-example | Information | An example for a media type can be provided in two ways: either directly in the Media Type Object using the example property or in the Schema Object definition when specifying the media type level schema property. If an example is provided at both levels, the Media Type Object level example will override the Schema Object level example. |
OPENAPI3STANDARDS_V133 | media-type-examples-override-media-schema-example | Information | An example for a media type can be provided in two ways: either directly in the Media Type Object using the examples property or in the Schema Object definition when specifying the media type level schema property. If an example is provided at both levels, the Media Type Object level examples will override the Schema Object level example. |
OPENAPI3STANDARDS_V134 | media-type-encoding-property-exists-in-schema | Error | If encoding information is provided for a Media Type Object, the encoding key must indicate name of the property which needs to be encoded. The property indicated this way must be pre-defined in the definition of the property schema of the Media Type Object. |
OPENAPI3STANDARDS_V135 | request-body-encoding-only-for-form-media-types | Warning | A Request Body Object can only define encoding information for its content if the media type of the content is specified as multipart or application/x-www-form-urlencoded. |
OPENAPI3STANDARDS_V136 | no-schema-content-media-type-for-pre-defined-file-media-type-value | Warning | The media type for a file upload can be specified in several ways e.g. by using the content key when defining the Media Type Object, the contentType property in the Media Type Object's encoding information, or the contentMediaType property in the Media Type Object's schema definition. When the media type is already specified using the Media Type Object's key, or by the contentType field of an Encoding Object, the contentMediaType keyword will be ignored if present. |
Encoding
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3STANDARDS_V145 | no-content-type-header-in-encoding-headers | Warning | The Content-Type header must not be explicitly defined in the Encoding Object headers section as it is described separately in the contentType section of the Encoding Object. If a definition is found, it will be ignored. |
OPENAPI3STANDARDS_V146 | request-body-encoding-headers-only-for-multipart-media-type | Warning | The Encoding Object referenced by a Request Body Object content definition must define headers only if the content has a multipart media type e.g. multipart/form-data. If headers are defined for a different request body media type, their definition will be ignored. |
OPENAPI3STANDARDS_V147 | valid-encoding-style | Error | The encoding style behavior follows the same values as those allowed for query parameters, including default values. Therefore, the property style in an Encoding Object can have only one of the following possible values: form, spaceDelimited, pipeDelimited or deepObject. All other values will be treated as invalid. |
OPENAPI3STANDARDS_V148 | encoding-space-delimited-style-only-for-array-type | Error | In an OpenAPI v3.0.x document, the spaceDelimited style can only be used when the type of the encoding property is set as array i.e. it cannot be used for primitive or object types. |
OPENAPI3STANDARDS_V149 | encoding-pipe-delimited-style-only-for-array-type | Error | In an OpenAPI v3.0.x document, the pipeDelimited style can only be used when the type of the encoding property is set as array i.e. it cannot be used for primitive or object types. |
OPENAPI3STANDARDS_V150 | encoding-deep-object-style-only-for-object-type | Error | The deepObject style can only be used when the type of the property is set as object i.e. it cannot be used for primitive or array types. |
OPENAPI3STANDARDS_V151 | request-body-encoding-style-only-for-form-url-encoded-media-type | Warning | In an OpenAPI v3.0.x document, the Encoding Object referenced by a Request Body Object content definition must define style only if the content media type is set as application/x-www-form-urlencoded. If style is defined for a different request body media type, it will be ignored. |
OPENAPI3STANDARDS_V152 | request-body-encoding-explode-only-for-form-url-encoded-media-type | Warning | In an OpenAPI v3.0.x document, the Encoding Object referenced by a Request Body Object content definition must configure explode only if the content media type is set as application/x-www-form-urlencoded. If explode is defined for a different request body media type, it will be ignored. |
OPENAPI3STANDARDS_V153 | request-body-encoding-allow-reserved-only-for-form-url-encoded-media-type | Warning | In an OpenAPI v3.0.x document, the Encoding Object referenced by a Request Body Object content definition must configure allowReserved only if the content media type is set as application/x-www-form-urlencoded. If allowReserved is defined for a different request body media type, it will be ignored. |
OPENAPI3STANDARDS_V154 | no-content-type-with-encoding-style | Warning | If the encoding style value is explicitly defined using the Encoding Object's style property, then the value of property contentType (implicit or explicit) will be ignored. |
OPENAPI3STANDARDS_V155 | no-content-type-with-encoding-explode | Warning | If the encoding explode value is explicitly defined using the Encoding Object's explode property, then the value of property contentType (implicit or explicit) will be ignored. |
OPENAPI3STANDARDS_V156 | no-content-type-with-encoding-allow-reserved | Warning | If the encoding configuration allows for reserved characters using the Encoding Object's allowReserved property, then the value of property contentType (implicit or explicit) will be ignored. |
OPENAPI3STANDARDS_V157 | encoding-space-delimited-style-only-for-array-or-object-types | Error | In an OpenAPI v3.1.x document, the spaceDelimited style can only be used when the type of the encoding property is set as array or object i.e. it cannot be used for primitive types. |
OPENAPI3STANDARDS_V158 | encoding-pipe-delimited-style-only-for-array-or-object-types | Error | In an OpenAPI v3.1.x document, the pipeDelimited style can only be used when the type of the encoding property is set as array or object i.e. it cannot be used for primitive types. |
OPENAPI3STANDARDS_V159 | request-body-encoding-style-only-for-form-media-types | Warning | In an OpenAPI v3.1.x document, the Encoding Object referenced by a Request Body Object content definition must define style only if the content media type is set as application/x-www-form-urlencoded or multipart/form-data. If style is defined for a different request body media type, it will be ignored. |
OPENAPI3STANDARDS_V160 | request-body-encoding-explode-only-for-form-media-types | Warning | In an OpenAPI v3.1.x document, the Encoding Object referenced by a Request Body Object content definition must configure explode only if the content media type is set as application/x-www-form-urlencoded or multipart/form-data. If explode is defined for a different request body media type, it will be ignored. |
OPENAPI3STANDARDS_V161 | request-body-encoding-allow-reserved-only-for-form-media-types | Warning | In an OpenAPI v3.1.x document, the Encoding Object referenced by a Request Body Object content definition must configure allowReserved only if the content media type is set as application/x-www-form-urlencoded or multipart/form-data. If allowReserved is defined for a different request body media type, it will be ignored. |
Responses
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3STANDARDS_V195 | unique-response-http-status-code | Error | Response keys are patterned fields that must have unique values within the Responses Object. The keys represent the HTTP status code/range for each response. |
OPENAPI3STANDARDS_V196 | at-least-one-response-code-in-responses | Error | The Responses Object must contain at least one response code which is recommended to be the response for a successful operation call. |
OPENAPI3STANDARDS_V197 | required-response-description | Error | The Response Object must define a short user-friendly description of the response using the description property. The description may provide details of what the response means, why the particular response was returned etc. e.g. if the corresponding response status is an error code, the description can provide users more details about why the error occurred. |
OPENAPI3STANDARDS_V198 | no-content-type-response-header-definition | Warning | The Content-Type header must not be explicitly defined in the Response Object headers section as the content section is dedicated for adding this information. If a definition is found, it will be ignored. |
Callbacks
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3STANDARDS_V215 | unique-callback-expression | Error | Callback Object keys are patterned fields that must have unique values. The keys represent the expression which is evaluated at runtime to identify a URL to use for the callback operation. |
OPENAPI3STANDARDS_V216 | valid-callback-url-expression | Error | Callback Object keys must be valid runtime expressions as defined by the OpenAPI specification. The expression is evaluated at runtime to determine the URL for the callback request. The expression must conform to the runtime expression ABNF grammar defined in the specification. |
Examples
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3STANDARDS_V225 | example-value-and-external-value-are-mutually-exclusive | Warning | The properties value and externalValue in Example Object are mutually exclusive. This means that in a Example Object instance, only one of these properties must be present at a time but not both. |
Links
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3STANDARDS_V235 | required-link-operation-ref-or-id | Error | The Link Object must identify the location of an Operation Object that it targets, using either the operationRef or operationId property. However, at one time, only one of these properties must be present and not both. |
OPENAPI3STANDARDS_V236 | link-operation-id-and-ref-are-mutually-exclusive | Warning | The properties operationId and operationRef in Link Object are mutually exclusive. This means that in a Link Object instance, only one of these properties must be present at a time but not both. |
OPENAPI3STANDARDS_V237 | link-operation-ref-points-to-an-operation-object | Error | The operationRef is a relative or absolute URI reference that must point to an OAS Operation Object. |
OPENAPI3STANDARDS_V238 | pre-defined-operation-for-link-operation-id | Error | The property operationId in the Link Object must refer uniquely to a pre-existing Operation Object in the current API document. |
Headers
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3STANDARDS_V245 | no-header-name-property | Error | An explicit name property must not be set in the Header Object since that is specified already when defining the headers map. |
OPENAPI3STANDARDS_V246 | no-header-location-property | Error | An explicit in property must not be specified in the Header Object to indicate location since the type of object already implicitly implies it to be header. |
OPENAPI3STANDARDS_V247 | valid-header-style | Error | For headers, only the simple style is applicable and rest will be treated as invalid. |
OPENAPI3STANDARDS_V248 | header-simple-style-only-for-array-type | Error | The simple style can only be used when the type of the header is set as array i.e. it cannot be used for primitive or object types. |
OPENAPI3STANDARDS_V249 | required-header-schema-or-content | Error | The Header Object must define the type schema for the header using either the schema or content property. The former is used more commonly while the latter is recommended for more complex scenarios involving media types. However, at one time, only one of these properties must be present and not both. |
OPENAPI3STANDARDS_V250 | header-schema-and-content-are-mutually-exclusive | Error | The properties schema and content in Header Object are mutually exclusive. This means that in a Header Object instance, only one of these properties must be present at a time but not both. |
OPENAPI3STANDARDS_V251 | header-example-and-examples-are-mutually-exclusive | Warning | The properties example and examples in Header Object are mutually exclusive. This means that in a Header Object instance, only one of these properties must be present at a time but not both. |
OPENAPI3STANDARDS_V252 | header-example-overrides-schema-example | Information | An example for a header can be provided in two ways: either directly in the Header Object using the example/examples property or in the Schema Object definition when specifying the header level schema property. If an example is provided at both levels, the Header Object level example will override the Schema Object level example. |
OPENAPI3STANDARDS_V253 | header-examples-override-schema-example | Information | An example for a header can be provided in two ways: either directly in the Header Object using the example/examples property or in the Schema Object definition when specifying the header level schema property. If an example is provided at both levels, the Header Object level examples will override the Schema Object level example. |
OPENAPI3STANDARDS_V254 | single-entry-header-content-map | Error | The content property of the Header Object is a map that contains representations of the header such that the key represents the media type while the value describes the header schema. This content map must contain only one entry. |
Tags
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3STANDARDS_V300 | required-tag-name | Error | The Tag Object must specify a user-friendly name for the tag using the name property. |
OPENAPI3STANDARDS_V301 | unique-tag-name | Error | The list of root OpenAPI Object level tags must have a unique name assigned to them in the Tag Object definition using the name property. |
References
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3STANDARDS_V310 | object-can-be-a-reference | Error | An OpenAPI object can be replaced by a Reference Object if the OpenAPI v3 Specification explicitly states that the value may be a reference. You can therefore, not use $ref in objects that do not allow replacement by a Reference Object. |
OPENAPI3STANDARDS_V311 | no-dollar-ref-sibling-properties | Warning | The Reference Object can only contain the property $ref and any sibling properties are not allowed. If specified, the additional properties will be ignored. |
OPENAPI3STANDARDS_V312 | valid-referenced-object | Information (disabled) | If Reference Object is used for referencing a component located elsewhere, then the type of the referenced component must match with the type of the object in place of which the Reference Object is used. The referenced component must also be valid in accordance with the rules set for the type of the object that uses the Reference Object e.g. if a Reference Object is used for referencing a Parameter Object the rules that apply on the Parameter Object will apply on the referenced component. |
Schemas
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3STANDARDS_V325 | valid-openapi-schema-type | Error | The property type in a Schema Object can have only of the following values: array, object, boolean, integer, number, string. Type null can also be used but only for OpenAPI 3.1.x documents. Other types are not allowed. |
OPENAPI3STANDARDS_V326 | schema-multiple-of-greater-than-zero | Error | The numeric validation keyword multipleOf must have a value that is strictly greater than zero (0). |
OPENAPI3STANDARDS_V327 | schema-non-negative-max-length | Error | The numeric validation keyword maxLength must have a non-negative integer value i.e. the value must be greater than or equal to 0. |
OPENAPI3STANDARDS_V328 | schema-non-negative-min-length | Error | The numeric validation keyword minLength must have a non-negative integer value i.e. the value must be greater than or equal to 0. |
OPENAPI3STANDARDS_V329 | required-array-schema-items | Error | The Schema Object of an OpenAPI 3.0.x document must define the array items using the items property if the schema type is set as array. |
OPENAPI3STANDARDS_V330 | schema-non-negative-max-items | Error | The numeric validation keyword maxItems must have a non-negative integer value i.e. the value must be greater than or equal to 0. |
OPENAPI3STANDARDS_V331 | schema-non-negative-min-items | Error | The numeric validation keyword minItems must have a non-negative integer value i.e. the value must be greater than or equal to 0. |
OPENAPI3STANDARDS_V332 | schema-non-negative-max-properties | Error | The numeric validation keyword maxProperties must have a non-negative integer value i.e. the value must be greater than or equal to 0. |
OPENAPI3STANDARDS_V333 | schema-non-negative-min-properties | Error | The numeric validation keyword minProperties must have a non-negative integer value i.e. the value must be greater than or equal to 0. |
OPENAPI3STANDARDS_V334 | at-least-one-property-in-schema-required-list | Error | If property required is specified in the Schema Object of an OpenAPI 3.0.x document, it must be a list containing at least one schema property name that needs to be marked as mandatory. |
OPENAPI3STANDARDS_V335 | unique-properties-in-schema-required-list | Error | A property can only be marked as required once in the list of required properties, specified using property required of the Schema Object i.e. the items in this list must be unique. |
OPENAPI3STANDARDS_V336 | schema-property-read-only-or-write-only-but-not-both | Error | A Schema Object property defined in an OpenAPI 3.0.x document under the properties property, cannot be marked as both read-only as well as write-only i.e. the property definition must not set both readOnly and writeOnly as true. |
OPENAPI3STANDARDS_V337 | discriminator-field-must-be-a-required-field | Error | The discriminator is the name of the property that decides which schema definition validates the structure of the model. This field must be marked as a required schema field. |
OPENAPI3STANDARDS_V338 | valid-default-value-type | Error | Default value must conform to the defined type for the Schema Object defined at the same level in an OpenAPI 3.0.x document. |
OPENAPI3STANDARDS_V339 | schema-valid-against-meta-schema | Error | The Schema Object or the JSON schema resource must be valid against the meta-schema identified by the URI in its $schema property. |
OPENAPI3STANDARDS_V340 | dollar-schema-only-for-root-schema-of-external-schema-resource | Error | If a schema definition is placed in an external/bare schema resource document (i.e. not an OpenAPI document), the $schema property must only be used in the root schema of that document as it applies to the lexical scope of the entire schema resource. It must not appear in non-resource root schema objects. |
OPENAPI3STANDARDS_V341 | unique-schema-types | Error | If multiple types are listed in the Schema Object using the type property, each type name in this array/list must be unique. |
OPENAPI3STANDARDS_V342 | valid-schema-content-encoding | Warning | Information about how a string value is encoded is provided using the Schema Object contentEncoding property which must be a valid encoding value from RFC 4648 or RFC 2045: base64url, base64, base32, base32hex, base16, hex, 7bit, 8bit, binary, quoted-printable, ietf-token, x-token. These values are compared in a case-insensitive manner. |
OPENAPI3STANDARDS_V343 | at-least-one-item-in-schema-all-of-list | Error | The allOf property in a Schema Object is a logical operator that helps infer data validity based on results of its subschemas. Therefore, if declared, it must contain at least one subschema in its list i.e. the allOf array must not be empty. |
OPENAPI3STANDARDS_V344 | at-least-one-item-in-schema-any-of-list | Error | The anyOf property in a Schema Object is a logical operator that helps infer data validity based on results of its subschemas. Therefore, if declared, it must contain at least one subschema in its list i.e. the anyOf array must not be empty. |
OPENAPI3STANDARDS_V345 | at-least-one-item-in-schema-one-of-list | Error | The oneOf property in a Schema Object is a logical operator that helps infer data validity based on results of its subschemas. Therefore, if declared, it must contain at least one subschema in its list i.e. the oneOf array must not be empty. |
OPENAPI3STANDARDS_V346 | schema-then-only-with-if-clause | Error | Property then can be used in a Schema Object along with the if clause to apply subschemas conditionally. When if is not present, the then property will be entirely ignored. |
OPENAPI3STANDARDS_V347 | schema-else-only-with-if-clause | Error | Property else can be used in a Schema Object along with the if clause to apply subschemas conditionally. When if is not present, the else property will be entirely ignored. |
OPENAPI3STANDARDS_V348 | at-least-one-item-in-schema-prefix-items-list | Error | The prefixItems property in a Schema Object helps validate each data instance against a subschema based on its position in the list. Therefore, if declared, it must contain at least one subschema in its list i.e. the prefixItems array must not be empty. |
OPENAPI3STANDARDS_V349 | schema-non-negative-max-contains | Error | The numeric validation keyword maxContains must have a non-negative integer value i.e. the value must be greater than or equal to 0. |
OPENAPI3STANDARDS_V350 | schema-non-negative-min-contains | Error | The numeric validation keyword minContains must have a non-negative integer value i.e. the value must be greater than or equal to 0. |
OPENAPI3STANDARDS_V351 | unique-schema-dependent-required-properties | Error | Each property in a Schema Object dependentRequired definition must consist of a list of properties that are dependent on it to be considered as required. The items in this list must be unique. |
Discriminators
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3STANDARDS_V400 | required-discriminator-property-name | Error | The Discriminator Object must specify the name of the property in the payload that will hold the discriminator value, using the propertyName property. |
OPENAPI3STANDARDS_V401 | no-additional-property-in-discriminator-object | Warning | In OpenAPI v3.0.x, the Discriminator Object cannot be extended with additional properties with or without the use of specification extensions (i.e. properties with names beginning with x-). Only the properties listed explicitly in the specification document for this object can be used and any other properties cannot be added. This rule does not apply to OpenAPI 3.1.x documents. |
Security Schemes
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3STANDARDS_V410 | required-security-scheme-type | Error | The Security Scheme Object must specify the type of the security scheme using the type property. |
OPENAPI3STANDARDS_V411 | valid-security-scheme-type | Error | The type of the security scheme specified using property type of the Security Scheme Object must have only one of the following values: apiKey, http, oauth2, openIdConnect. Type mutualTLS can also be used but only for OpenAPI v3.1.x documents. Other types are not supported or allowed. |
OPENAPI3STANDARDS_V412 | required-api-key-security-scheme-parameter-name | Error | If the security scheme type is API Key (i.e. type is set to apiKey), the Security Scheme Object must specify a name for the API Key parameter using the name property. |
OPENAPI3STANDARDS_V413 | required-api-key-security-scheme-parameter-location | Error | If the security scheme type is API Key (i.e. type is set to apiKey), the Security Scheme Object must specify a location for the API Key parameter using the in property. Valid values for location include query, header and cookie. |
OPENAPI3STANDARDS_V414 | valid-api-key-security-scheme-parameter-location | Error | The location of the API key specified using property in of the Security Scheme Object must have only one of the following values: query, header, cookie. Other types are not supported nor allowed. |
OPENAPI3STANDARDS_V415 | required-scheme-of-http-security-scheme | Error | If the security scheme type is HTTP (i.e. type is set to http), the Security Scheme Object must specify a name of the HTTP Authorization scheme to be used in the Authorization header as defined in RFC7235, using the scheme property. The value of the scheme used should be registered in the IANA Authentication Scheme registry. |
OPENAPI3STANDARDS_V416 | required-oauth2-security-scheme-flows | Error | If the security scheme type is OAuth 2.0 (i.e. type is set to oauth2), the Security Scheme Object must specify an object containing configuration information for the flow types supported, using the flows property. |
OPENAPI3STANDARDS_V417 | required-open-id-connect-security-scheme-url | Error | If the security scheme type is OpenId Connect (i.e. type is set to openIdConnect), the Security Scheme Object must specify the OpenId Connect URL to discover OAuth2 configuration values, using the openIdConnectUrl property. |
OAuth 2.0 Flows
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3STANDARDS_V440 | required-oauth2-flow-authorization-url | Error | If the flow type is set as implicit or authorizationCode in the OAuth Flows Object, then the OAuth Flow Object must specify the authorization URL to be used for this flow, using the authorizationUrl property. |
OPENAPI3STANDARDS_V441 | required-oauth2-flow-token-url | Error | If the flow type is set as password, clientCredentials or authorizationCode in the OAuth Flows Object, then the OAuth Flow Object must specify the token URL to be used for this flow, using the tokenUrl property. |
OPENAPI3STANDARDS_V442 | required-oauth2-flow-scopes | Error | For all flow types, the OAuth Flow Object must specify the available scopes for the OAuth2 security scheme token URL, using the scopes property. |
OPENAPI3STANDARDS_V443 | required-revoke-token-url | Error | When the x-revoke-token extension is used in an OAuth Flow Object, it must include the Url property that defines the endpoint for revoking tokens. |
Security Requirements
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3STANDARDS_V450 | unique-security-requirement-scheme-name | Error | The security requirement keys are patterned fields that must have unique values within the Security Requirement Object. The keys represent the names of the security schemes that need to be applied on an operation. |
OPENAPI3STANDARDS_V451 | empty-security-requirement-property-array-for-non-oauth2-non-open-id-connect-schemes | Error | In an OpenAPI v3.0.x document, the Security Requirement Object property value allows specifying scope values for OAuth 2.0 and OpenId Connect security schemes. For all other security scheme types (i.e. for type not set as oauth2 or openIdConnect), the property value must be set as an empty array. |
OPENAPI3STANDARDS_V452 | pre-defined-security-scheme-for-applying-security | Error | The name specified for the security scheme in the Security Requirement Object must correspond with a Security Scheme definition in the global security schemes defined under the Components Object. |
Specification Extensions
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3STANDARDS_V460 | unique-specification-extension-name | Error | Specification extensions are patterned fields that must have unique values within the object they are extending. The keys represent the names assigned to the vendor extensions that must be prefixed by 'x-'. |
Runtime Expressions
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3STANDARDS_V465 | pre-defined-operation-parameters-for-expression-request-parameter-source | Error | In runtime expression when using the request parameter source location, request parameters must be declared in the parameters section of the parent operation or they cannot be evaluated. This includes request headers. |