Define & Validate APIsValidation RulesetsOpenAPI Rulesets
OpenAPI v3 Standards Linting
Linting checks performed on provided OpenAPI v3 file to check its conformance to recommended practices defined in the OpenAPI standard document.
| Property | Value |
|---|---|
| Ruleset ID | openapi-v3-standards-linting |
| Code prefix | OPENAPI3STANDARDS_L |
| Type | Linting |
| Default severity | Warning |
| Rule system | Semantic |
| Rules | 83 |
Rules marked (disabled) are turned off by default, so they don't report issues.
OpenAPI Root Information
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3STANDARDS_L001 | valid-openapi-file-naming-conventions | Information | The root OpenAPI document is recommended to be named as either openapi.json or openapi.yaml depending upon the data format used in the file. |
Server Variables
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3STANDARDS_L010 | at-least-one-item-in-server-variable-enum-list | Warning | 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 should not be empty. |
OPENAPI3STANDARDS_L011 | valid-server-variable-default-value-for-enum | Warning | If a default value is provided for the server variable and an enumeration list is also defined using the enum property, the default value should exist in this list. |
Paths
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3STANDARDS_L020 | no-ambiguous-path | Warning | Templated paths should not lead to an ambiguous resolution e.g. /{entity}/me and /books/{id} can result in the same path depending upon the values substituted and so are considered ambiguous. |
Path Items
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3STANDARDS_L030 | path-item-field-either-in-referenced-or-defined-object | Information | In case a Path Item Object field appears both in the defined object and the referenced object, the behavior is undefined. |
Operations
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3STANDARDS_L040 | operation-parameter-redefines-path-object-parameter | Information | If a parameter is defined under the parameters property of the Operation Object as well as in the Path Item Object level parameters, the Operation Object level parameter definition will override the definition found in the Path Item Object parameters but will not remove it. |
OPENAPI3STANDARDS_L041 | operation-security-overrides-root-security | Information | If security mechanisms are declared for the operation using the security property, they will override any security applied at top level i.e. in the OpenAPI Object. To remove a top-level security declaration, an empty array can be used. |
OPENAPI3STANDARDS_L042 | operation-servers-redefine-root-and-path-servers | Information | If servers are defined at Operation Object level as well as at either Path Item Object level or root OpenAPI Object level, the Operation Object level servers will override the servers defined elsewhere (Path Item Object or at root level). |
OPENAPI3STANDARDS_L043 | 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. Therefore, in OpenAPI as well, the GET Operation Object must not set the requestBody property. |
OPENAPI3STANDARDS_L044 | 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_L045 | 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. |
Parameters
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3STANDARDS_L060 | unique-case-insensitive-header-parameter-names | Warning | The parameters list can contain custom headers that are expected as part of the request. There can only be a single entry for each header in this list. Since the header names are case insensitive as per RFC7230 they will be compared accordingly. |
OPENAPI3STANDARDS_L061 | no-allow-empty-value-usage | Warning | Use of the property allowEmptyValue, which allows sending a parameter with an empty value, is not recommended as it is likely going to be removed from the OpenAPI standards in a later revision. |
OPENAPI3STANDARDS_L062 | allow-empty-value-only-for-query-parameter | Warning | Property allowEmptyValue is only valid for query parameters (i.e. parameter location is set to query) and allows sending a parameter with an empty value. This property cannot be used with any other types of parameters e.g. path, header, or cookie. |
OPENAPI3STANDARDS_L063 | parameter-explode-only-for-array-or-object-types | Information | When parameter explode is true, parameter values of type array or object generate separate parameters for each value of the array or key-value pair of the map. For other types of parameters this property has no effect. |
OPENAPI3STANDARDS_L064 | allow-reserved-only-for-query-parameter | Warning | Property allowReserved is only valid for query parameters (i.e. parameter location is set to query) and helps determine whether the parameter value should allow reserved characters. This property cannot be used with any other types of parameters e.g. path, header, or cookie. |
OPENAPI3STANDARDS_L065 | valid-parameter-example | Warning | The example value specified for the Parameter Object using either the example property or examples must be valid for the schema definition and encoding properties (if present) of that parameter. |
Media Types
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3STANDARDS_L080 | valid-media-type-example | Warning | The example value provided for a Media Type Object using either the example property or examples must be in a correct format with respect to the media type and valid for the specified schema definition (if present). |
OPENAPI3STANDARDS_L081 | multipart-property-content-media-type-only-with-content-encoding | Warning | Use of contentMediaType without contentEncoding is not recommended for multipart property definitions. Per the JSON Schema specification, contentMediaType without contentEncoding present is treated as if contentEncoding: identity were present. While useful for embedding text documents such as text/html into JSON strings, it is not useful for a multipart/form-data part, as it just causes the document to be treated as text/plain instead of its actual media type. |
Encoding
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3STANDARDS_L090 | encoding-explode-only-for-array-or-object-types | Information | When encoding explode is true, property values of type array or object generate separate parameters for each value of the array or key-value pair of the map. For other types of properties the explode attribute will have no effect. |
Responses
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3STANDARDS_L100 | response-code-overrides-response-range | Information | The Responses Object supports explicit response codes as well as response ranges. If a response is defined using an explicit code and a response range definition also exists for the same code, the explicit code definition takes precedence over the range definition. |
OPENAPI3STANDARDS_L101 | at-least-one-success-response-exists | Warning | The Responses Object must contain at least one response code which should be the response for a successful operation call e.g. 200. |
OPENAPI3STANDARDS_L102 | unique-case-insensitive-response-header-names | Warning | The response headers list can contain the expected headers that can be received as part of the response. There can only be a single entry for each header in this list. Since the header names are case insensitive as per RFC7230 they will be compared accordingly. |
Examples
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3STANDARDS_L120 | valid-example-value-for-associated-schema | Warning | The example value specified in the Example Object using the value property must be compatible with the associated type schema definition. |
Headers
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3STANDARDS_L130 | no-allow-empty-value-in-header | Warning | Property allowEmptyValue is only valid for query parameters (i.e. parameter location is set to query) and allows sending a parameter with an empty value. This property cannot be used inside a header. |
OPENAPI3STANDARDS_L131 | header-explode-only-for-array-or-object-types | Information | When the header explode is set to true, the header values of type array or object generate separate parameters for each value of the array or key-value pair of the map. For other types of headers this property has no effect. |
OPENAPI3STANDARDS_L132 | no-allow-reserved-in-header | Warning | Property allowReserved is only valid for query parameters (i.e. parameter location is set to query) and allows sending a parameter with reserved characters. This property cannot be used inside a header. |
OPENAPI3STANDARDS_L133 | valid-header-example | Warning | The example value specified for the Header Object using either the example property or examples must be valid for the schema definition and encoding properties (if present) of that header. |
References
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3STANDARDS_L140 | resolvable-reference | Error | The reference path provided in the Reference Object using the $ref property must be resolvable i.e. it must be a valid URI (relative or absolute) and should yield the referenced JSON value. |
OPENAPI3STANDARDS_L141 | reference-object-summary-overrides-referenced-object-summary | Information | If the property summary is specified in the Reference Object as a sibling of property $ref and also specified in the object referenced using $ref, the Reference Object level summary will override the one provided in the referenced object. |
OPENAPI3STANDARDS_L142 | referenced-object-allows-summary-override | Information | If the property summary is specified in the Reference Object as a sibling of property $ref, it is expected to override one specified in the referenced object provided that the referenced object supports a summary. If it does not, the Reference Object level summary has no effect. |
OPENAPI3STANDARDS_L143 | reference-object-description-overrides-referenced-object-description | Information | If the property description is specified in the Reference Object as a sibling of property $ref and also specified in the object referenced using $ref, the Reference Object level description will override the one provided in the referenced object. |
OPENAPI3STANDARDS_L144 | referenced-object-allows-description-override | Information | If the property description is specified in the Reference Object as a sibling of property $ref, it is expected to override one specified in the referenced object provided that the referenced object supports a description. If it does not, the Reference Object level description has no effect. |
Schemas
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3STANDARDS_L150 | at-least-one-item-in-schema-enum-list | Warning | If property enum is specified in the Schema Object, it must consist of at least one item in the list. |
OPENAPI3STANDARDS_L151 | unique-schema-enum-list-items | Warning | If property enum is specified in the Schema Object, it must consist of only unique items in the list. |
OPENAPI3STANDARDS_L152 | valid-schema-example | Warning | The example value specified for the Schema Object using the example property should be valid for the type definition of that schema. |
OPENAPI3STANDARDS_L153 | read-only-for-properties-schema-only | Warning | A Schema Object in an OpenAPI 3.0.x document can be marked as read-only using the readOnly attribute only if it is defining a schema property i.e. readOnly is relevant only for Schema Object properties schema definitions. |
OPENAPI3STANDARDS_L154 | write-only-for-properties-schema-only | Warning | A Schema Object in an OpenAPI 3.0.x document can be marked as write-only using the writeOnly attribute only if it is defining a schema property i.e. writeOnly is relevant only for Schema Object properties schema definitions. |
OPENAPI3STANDARDS_L155 | no-schema-xml-in-root-schema | Warning (disabled) | A Schema Object can add XML related metadata using the xml property. This metadata is only effective if the schema under consideration is not a root schema e.g. it may be used in a schema property definition from a Schema Object properties but not in a schema defined/referenced directly under the Parameter Object, Header Object or a Media Type Object. |
OPENAPI3STANDARDS_L156 | required-dollar-id-in-root-schema | Warning | The root schema of a JSON Schema document or a root Schema Object defined/referenced directly in a component of an OpenAPI document (e.g. Parameter Object, Header Object or a Media Type Object) should contain the $id property which uniquely identifies the schema and also helps indicate the Base URI for resolving relative references within the schema definition. The value of $id must be a valid absolute URI as per RFC3986. This URI must contain a scheme, but no fragment. |
OPENAPI3STANDARDS_L157 | dollar-schema-overrides-default-oas-schema-dialect | Information | If $schema is defined explicitly in a Schema Object of the OpenAPI document, it overrides the default schema dialect specified using jsonSchemaDialect in the OpenAPI Object or the implicit OpenAPI dialect schema Id https://spec.openapis.org/oas/3.1/dialect/base if jsonSchemaDialect is not set. An exception to this rule is for schemas defined in external non-OAS documents. |
OPENAPI3STANDARDS_L158 | schema-prefix-items-only-for-arrays | Warning | The property prefixItems can only be used for Schema Objects when the type is either unspecified (implying any type) or set as array. This property is not applicable for any other types. |
OPENAPI3STANDARDS_L159 | schema-items-only-for-arrays | Warning | The property items can only be used for Schema Objects when the type is either unspecified (implying any type) or set as array. This property is not applicable for any other types. |
OPENAPI3STANDARDS_L160 | schema-unevaluated-items-only-for-arrays | Warning | The property unevaluatedItems can only be used for Schema Objects when the type is either unspecified (implying any type) or set as array. This property is not applicable for any other types. |
OPENAPI3STANDARDS_L161 | schema-max-items-only-for-arrays | Warning | The property maxItems can only be used for Schema Objects when the type is either unspecified (implying any type) or set as array. This property is not applicable for any other types. |
OPENAPI3STANDARDS_L162 | schema-min-items-only-for-arrays | Warning | The property mniItems can only be used for Schema Objects when the type is either unspecified (implying any type) or set as array. This property is not applicable for any other types. |
OPENAPI3STANDARDS_L163 | schema-unique-items-only-for-arrays | Warning | The property uniqueItems can only be used for Schema Objects when the type is either unspecified (implying any type) or set as array. This property is not applicable for any other types. |
OPENAPI3STANDARDS_L164 | schema-contains-only-for-arrays | Warning | The property contains can only be used for Schema Objects when the type is either unspecified (implying any type) or set as array. This property is not applicable for any other types. |
OPENAPI3STANDARDS_L165 | schema-max-contains-only-for-arrays | Warning | The property maxContains can only be used for Schema Objects when the type is either unspecified (implying any type) or set as array. This property is not applicable for any other types. |
OPENAPI3STANDARDS_L166 | schema-contains-exists-for-max-contains | Warning | The property maxContains should only be used when the property contains is also set in the same Schema Object. If contains is not present, maxContains has no effect. |
OPENAPI3STANDARDS_L167 | schema-min-contains-only-for-arrays | Warning | The property minContains can only be used for Schema Objects when the type is either unspecified (implying any type) or set as array. This property is not applicable for any other types. |
OPENAPI3STANDARDS_L168 | schema-contains-exists-for-min-contains | Warning | The property minContains should only be used when the property contains is also set in the same Schema Object. If contains is not present, minContains has no effect. |
OPENAPI3STANDARDS_L169 | schema-properties-only-for-objects | Warning | The property properties can only be used for Schema Objects when the type is either unspecified (implying any type) or set as object. This property is not applicable for any other types. |
OPENAPI3STANDARDS_L170 | schema-pattern-properties-only-for-objects | Warning | The property patternProperties can only be used for Schema Objects when the type is either unspecified (implying any type) or set as object. This property is not applicable for any other types. |
OPENAPI3STANDARDS_L171 | schema-additional-properties-only-for-objects | Warning | The property additionalProperties can only be used for Schema Objects when the type is either unspecified (implying any type) or set as object. This property is not applicable for any other types. |
OPENAPI3STANDARDS_L172 | schema-property-names-only-for-objects | Warning | The property propertyNames can only be used for Schema Objects when the type is either unspecified (implying any type) or set as object. This property is not applicable for any other types. |
OPENAPI3STANDARDS_L173 | schema-unevaluated-properties-only-for-objects | Warning | The property unevaluatedProperties can only be used for Schema Objects when the type is either unspecified (implying any type) or set as object. This property is not applicable for any other types. |
OPENAPI3STANDARDS_L174 | schema-max-properties-only-for-objects | Warning | The property maxProperties can only be used for Schema Objects when the type is either unspecified (implying any type) or set as object. This property is not applicable for any other types. |
OPENAPI3STANDARDS_L175 | schema-min-properties-only-for-objects | Warning | The property minProperties can only be used for Schema Objects when the type is either unspecified (implying any type) or set as object. This property is not applicable for any other types. |
OPENAPI3STANDARDS_L176 | schema-required-only-for-objects | Warning | The property required can only be used for Schema Objects when the type is either unspecified (implying any type) or set as object. This property is not applicable for any other types. |
OPENAPI3STANDARDS_L177 | schema-dependent-required-only-for-objects | Warning | The property dependentRequired can only be used for Schema Objects when the type is either unspecified (implying any type) or set as object. This property is not applicable for any other types. |
OPENAPI3STANDARDS_L178 | schema-multiple-of-only-for-numbers | Warning | The property multipleOf can only be used for Schema Objects when the type is either unspecified (implying any type), set as number or as integer. This property is not applicable for any other types. |
OPENAPI3STANDARDS_L179 | schema-maximum-only-for-numbers | Warning | The property maximum can only be used for Schema Objects when the type is either unspecified (implying any type), set as number or as integer. This property is not applicable for any other types. |
OPENAPI3STANDARDS_L180 | schema-exclusive-maximum-only-for-numbers | Warning | The property exclusiveMaximum can only be used for Schema Objects when the type is either unspecified (implying any type), set as number or as integer. This property is not applicable for any other types. |
OPENAPI3STANDARDS_L181 | schema-minimum-only-for-numbers | Warning | The property minimum can only be used for Schema Objects when the type is either unspecified (implying any type), set as number or as integer. This property is not applicable for any other types. |
OPENAPI3STANDARDS_L182 | schema-exclusive-minimum-only-for-numbers | Warning | The property exclusiveMinimum can only be used for Schema Objects when the type is either unspecified (implying any type), set as number or as integer. This property is not applicable for any other types. |
OPENAPI3STANDARDS_L183 | schema-max-length-only-for-strings | Warning | The property maxLength can only be used for Schema Objects when the type is either unspecified (implying any type) or set as string. This property is not applicable for any other types. |
OPENAPI3STANDARDS_L184 | schema-min-length-only-for-strings | Warning | The property minLength can only be used for Schema Objects when the type is either unspecified (implying any type) or set as string. This property is not applicable for any other types. |
OPENAPI3STANDARDS_L185 | schema-pattern-only-for-strings | Warning | The property pattern can only be used for Schema Objects when the type is either unspecified (implying any type) or set as string. This property is not applicable for any other types. |
OPENAPI3STANDARDS_L186 | schema-content-encoding-only-for-strings | Warning | The property contentEncoding can only be used for Schema Objects when the type is either unspecified (implying any type) or set as string. This property is not applicable for any other types. |
OPENAPI3STANDARDS_L187 | schema-content-media-type-only-for-strings | Warning | The property contentMediaType can only be used for Schema Objects when the type is either unspecified (implying any type) or set as string. This property is not applicable for any other types. |
OPENAPI3STANDARDS_L188 | schema-content-schema-only-for-strings | Warning | The property contentSchema can only be used for Schema Objects when the type is either unspecified (implying any type) or set as string. This property is not applicable for any other types. |
OPENAPI3STANDARDS_L189 | schema-content-media-type-exists-for-content-schema | Warning | The property contentSchema should only be used when the property contentMediaType is also set in the same Schema Object. If contentMediaType is not present, contentSchema will be ignored. |
OPENAPI3STANDARDS_L190 | valid-schema-default-value | Warning | The default value specified for the Schema Object using the default property should be valid for the type definition of that schema. |
OPENAPI3STANDARDS_L191 | valid-schema-examples | Warning | Each of the example provided for a Schema Object using the examples property should be valid for the type definition of that schema. |
OPENAPI3STANDARDS_L192 | no-schema-example-usage | Warning | Use of the property example has been deprecated by OpenAPI in favor of the JSON Schema examples keyword. Use of property example is discouraged as later versions of the OpenAPI specification may remove it. |
Discriminators
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3STANDARDS_L250 | no-inline-schemas-in-polymorphism | Error | Inline schema definitions, which do not have a given id, cannot be used in polymorphism. When using the discriminator, inline schemas will not be considered. |
XML
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3STANDARDS_L260 | required-xml-name-for-arrays | Warning | When using arrays, XML element names are not inferred (for singular/plural forms) and the name property should be used to add that information. For wrapped schemas, the name should be specified outside the items schema for the wrapping element and inside the items schema for the inner elements. For non-wrapped schemas, the name should be specified inside the items schema only. |
OPENAPI3STANDARDS_L261 | array-level-xml-name-for-wrapped-schemas-only | Warning | When XML name is defined alongside type being array (outside the items), it will only affect the wrapping element. Therefore, it should be set only if wrapped is true. If wrapped is false, it will be ignored. |
OPENAPI3STANDARDS_L262 | xml-wrapped-only-for-arrays | Warning | The XML wrapped definition takes effect only when defined alongside type being array (outside the items). This means that the property wrapped in the xml definition must be used only if the schema type is set as array. |
Security Schemes
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3STANDARDS_L270 | use-registered-http-security-scheme-value | Warning | If you have defined a security scheme of type set as http you also need to provide a name of the HTTP Authorization scheme using the scheme property. The value of this HTTP security scheme should be registered in the IANA Authentication Scheme registry. |
OPENAPI3STANDARDS_L271 | no-oauth2-implicit-flow-usage | Information | As of 2020, the OAuth 2.0 implicit flow is about to be deprecated by OAuth 2.0 Security Best Current Practice. Therefore, using the implicit flow in an OAuth Flows Object of a oauth2 security scheme is not recommended. |
Miscellaneous
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3STANDARDS_L281 | callback-operation-required-warning | Warning | Each callback method entry should define a valid operation object. Null or invalid operation entries are ignored during callback processing. |
Learn more
OpenAPI v3 Syntax Linting
Linting checks performed on provided OpenAPI v3 file to check its conformance to recommended syntax practices by the OpenAPI v3 official standards document.
OpenAPI v3 APIMatic Linting
Linting checks performed by APIMatic on provided OpenAPI v3 file to check its conformance to recommended practices for better API consumption.