Define & Validate APIsValidation RulesetsOpenAPI Rulesets
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.
| Property | Value |
|---|---|
| Ruleset ID | openapi-v3-apimatic-linting |
| Code prefix | OPENAPI3APIMATIC_L |
| Type | Linting |
| Default severity | Warning |
| Rule system | Semantic |
| Rules | 194 |
Rules marked (disabled) are turned off by default, so they don't report issues.
OpenAPI Root Information
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3APIMATIC_L001 | unique-role-id | Error | Role IDs specified in the API role definitions must be unique. |
OpenAPI Info
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3APIMATIC_L040 | non-empty-info-title | Error | The title of the application in the info object must be non-empty and non-null. |
OPENAPI3APIMATIC_L041 | non-empty-info-version | Error | In the OpenAPI 3.0 specification, the info version is a required property. The info object must contain non-null, non-empty and valid version property. |
OpenAPI Licenses
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3APIMATIC_L080 | non-empty-license-name | Error (disabled) | In the OpenAPI 3.0 specification, the license name is a required property. The license object must contain a non-null, non-empty and valid name property. |
OpenAPI Servers
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3APIMATIC_L100 | server-configuration-extension-used | Warning (disabled) | In OpenAPI v3.0.x, the Info Object can be extended with additional properties through the use of specification extensions (i.e., properties that begin with x-). One such vendor extension is x-server-configuration, which allows users to define API server configurations in more detail. It is essential to include the x-server-configuration extension in the Info Object, as it should not be missing. |
OPENAPI3APIMATIC_L101 | pre-defined-environment-for-default-environment | Error | The default environment specified in the server configuration extension must have a corresponding definition in the server configuration environments. |
OPENAPI3APIMATIC_L102 | pre-defined-server-for-default-server | Error | The default server specified in the server configuration of the API must have a corresponding definition in all of the server configuration environment servers. |
OPENAPI3APIMATIC_L103 | unique-environment | Error | The environments defined in the server configuration of the API must have unique names. |
OPENAPI3APIMATIC_L104 | required-environment-name | Error | A non-null, non-empty, user-friendly name or identifier must be provided for the environment name. |
OPENAPI3APIMATIC_L105 | same-server-sets | Error | The server sets of environments in the server configuration of the API must be the same i.e. the total number of servers and their names in each environment must be the same. |
OPENAPI3APIMATIC_L106 | unique-server | Error | The servers defined for an environment in the server configuration of the API must have unique names. |
OPENAPI3APIMATIC_L107 | required-server-name | Error | A non-null, non-empty, user-friendly name or identifier must be provided for the server name. |
OPENAPI3APIMATIC_L108 | required-server-url | Error | A server object defined for the environment must specify a non-empty, non-null and absolute URL path. |
OPENAPI3APIMATIC_L109 | unique-server-url | Error | There are two or more server objects defined in the same environment that have the same URL. This can cause confusion for clients that are trying to connect to the API and can result in unexpected behavior. Therefore, it is important to ensure that each server in the environment has a unique URL. |
OPENAPI3APIMATIC_L110 | server-url-uses-https | Warning (disabled) | You must only use HTTPS for the server transport protocol. |
OPENAPI3APIMATIC_L111 | pre-defined-server-variable-for-server-url-template-expression | Error | Variable substitutions can be made when a variable is named within {brackets} in a server URL. Each variable declared this way must be defined explicitly in the variables property of the Server Object. |
OPENAPI3APIMATIC_L112 | pre-defined-server-parameter-for-server-url-template-expression | Error | A parameter referenced by a server (a path or template parameter) must have a corresponding definition in the server configuration for server url template expression. |
OPENAPI3APIMATIC_L113 | unique-server-variables-key | Error | The server variables key defined in the server of the API must have unique names. |
OPENAPI3APIMATIC_L114 | unique-server-parameters | Error | The server parameters defined in the server configuration of the API must have unique names. |
OPENAPI3APIMATIC_L115 | server-variable-exists-in-server-url-template | Warning | Server variables defined in the server's variables object must be referenced in the server URL. |
OPENAPI3APIMATIC_L116 | server-parameter-exists-in-server-url-template | Warning | Template parameters defined in the server configuration must be referenced by at least one or more server URLs. |
OPENAPI3APIMATIC_L117 | non-empty-server-variables-key | Error | Variable key in the server object of the API must specify a non-empty non-null name. |
OPENAPI3APIMATIC_L118 | required-server-parameter-name | Error | Server parameter definition in the server configuration of the API must specify a non-empty non-null name. |
OPENAPI3APIMATIC_L119 | required-server-parameter-type | Error | Server parameter definition in the server configuration of the API must specify a type. |
OPENAPI3APIMATIC_L120 | valid-server-parameter-type | Error | Valid types for a server parameter include: String, Number and a String/Number enumeration. No other types must be used. |
OPENAPI3APIMATIC_L121 | server-parameter-cannot-be-array | Error | Server URL parameters cannot be declared as arrays. Only primitive types like string, number or string/number enumeration types are allowed. |
OPENAPI3APIMATIC_L122 | server-parameter-cannot-be-map | Error | Server URL parameters cannot be declared as maps. Only primitive types like string, number or string/number enumeration types are allowed. |
OPENAPI3APIMATIC_L123 | server-parameter-cannot-be-constant | Error | A server URL template with a parameter allows the user to substitute a value into the URL at runtime, such as for different environments. Declaring a parameter as a constant would make it impossible to substitute different values into the URL. Hence, server URL parameter cannot be declared as constant. |
OPENAPI3APIMATIC_L124 | non-empty-server-variable-default | Error | The default value for a server variable object must be specified and should not be null or empty. The default value is used to resolve the server URL. Not defining a default value can result in unexpected behavior when resolving the URL for the API. |
OPENAPI3APIMATIC_L125 | required-server-parameter-schema-default | Error | Server parameter definition in the server configuration of the API must specify a non-empty, non-null default value in schema object. |
OPENAPI3APIMATIC_L126 | valid-server-parameter-schema-default | Error | The schema default value specified in the server parameter definition must be valid according to the type definition of this parameter. |
OpenAPI Components
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3APIMATIC_L150 | at-least-one-component-reference | Warning | A component that is defined globally using the 'components' root object property must be referenced at least once by any other object in the API specification document. Referencing is performed using $ref. |
OPENAPI3APIMATIC_L151 | non-empty-schema-component-key | Error | The unique key specified for the schema in the components object must be non-empty. |
OPENAPI3APIMATIC_L152 | unique-schema-component-key | Error | Each schema component must have a unique name, duplicate names are not allowed as they can lead to confusion and potential conflicts. |
OPENAPI3APIMATIC_L153 | non-empty-security-scheme-component-key | Error | When a security scheme is defined in the components object, the key specified for it must be non-empty. |
OpenAPI Paths
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3APIMATIC_L180 | non-empty-paths-key | Error | An empty path key in OpenAPI is discouraged as it may lead to confusion and ambiguity in identifying the targeted resource in the server. Therefore, it is recommended to use non-empty path keys that accurately point to the intended resource in the server. This improves the clarity, readability, and maintainability of the API documentation, and ensures that the server responds appropriately to client requests. |
OPENAPI3APIMATIC_L181 | no-query-string-in-path | Warning | The path key cannot contain a query string for specifying parameter values. |
OpenAPI Operations
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3APIMATIC_L230 | operation-id-exists | Error | The Operation Object must specify a unique identifier for the operation in the API document using the operationId property. This id is used by the code generation engine to generate relevant components tied to an endpoint. |
OPENAPI3APIMATIC_L231 | at-least-one-operation-tag | Warning | The Operation Object must specify one or more tags using the tags property. Tags are used for logical grouping of operations. This facilitates their discovery and consequently eases API consumption. |
OPENAPI3APIMATIC_L232 | non-empty-operation-tag | Error | Tags list defined inside operation object must contain non-null and non-empty tags. |
OPENAPI3APIMATIC_L233 | unique-operation-tag | Error | Avoid duplicate operation tags in OpenAPI to prevent confusion and inconsistencies in the API documentation. Use distinct tags for each set of related operations to improve the API's quality and usability. |
OPENAPI3APIMATIC_L234 | alphabetical-operation-tags | Warning (disabled) | Tags defined within the operation object must be in alphabetical order. |
OPENAPI3APIMATIC_L235 | pre-defined-operation-tag-in-global-tags | Warning | Each tag used in the API must be defined in the root level tags list of the API specification. This ensures that all tags used in the API are properly defined, which helps with documentation generation and other tooling. Please check the root level tags list and ensure that all tags used in the API are properly defined. |
OPENAPI3APIMATIC_L236 | pre-defined-operation-server-in-server-configuration | Error | Operation must use a pre-defined server from the API specification's server configuration. |
OPENAPI3APIMATIC_L237 | required-request-body-for-post-operation | Warning (disabled) | A request body is required for HTTP POST method. Please ensure that the operation with the POST method has a properly defined request body. Check the schema and properties of the request body to ensure that they are correctly defined. If the operation does not require a request body, consider using a different HTTP method such as GET, PUT or DELETE instead. |
OPENAPI3APIMATIC_L238 | no-dynamic-form-parameters-in-get-operation | Error | HTTP Methods like GET do not support dynamic form parameters therefore, the allowDynamicFormParameters flag must be disabled for all GET methods. |
OPENAPI3APIMATIC_L239 | no-dynamic-form-parameters-in-delete-operation | Error | HTTP Methods like DELETE do not support dynamic form parameters therefore, the allowDynamicFormParameters flag must be disabled for all DELETE methods. |
OPENAPI3APIMATIC_L240 | no-dynamic-form-parameters-in-head-operation | Error | HTTP Methods like HEAD do not support dynamic form parameters therefore, the allowDynamicFormParameters flag must be disabled for all HEAD methods. |
OpenAPI Parameters
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3APIMATIC_L330 | non-empty-parameter-name | Error | Parameter must contain non-null and non-empty name. |
OPENAPI3APIMATIC_L331 | unique-parameter-name | Error | Operation level parameter names and requestBody schema property names should be unique. You can use parameter-level x-unique-name to provide unique display name to conflicting parameter. |
OpenAPI Request Body
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3APIMATIC_L370 | at-least-one-entry-in-request-body-content | Error | The content property is required for a request body object. Hence, it must not be missing or empty and it must contain at least one entry. |
OpenAPI Media Types
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3APIMATIC_L400 | required-media-type-schema | Error | Each media type object must have an associated schema defined. The schema defines the structure and data format for the content of the media type. |
OpenAPI Responses
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3APIMATIC_L460 | unique-responses-key | Error | Each response must have a unique http status code to clearly identify its purpose and differentiate it from other responses. |
OPENAPI3APIMATIC_L461 | sorted-responses-keys | Warning | Response codes must be sorted in an ascending/increasing order. |
OPENAPI3APIMATIC_L462 | at-least-one-operation-4XX-response | Warning (disabled) | An operation should have at least one 4XX response defined to indicate that an error may be returned by the API. Please check the responses section of the operation and ensure that at least one 4XX response is properly defined. It is recommended to provide a detailed description of the error in the response message to help clients understand the issue. |
OPENAPI3APIMATIC_L463 | no-response-content-implies-reponse-with-no-body | Information | If a response does not contain a content object, it implies that there is no response body expected. |
OPENAPI3APIMATIC_L464 | required-2XX-response-content-for-get-operation | Warning (disabled) | GET operations are generally expected to return some form of data for a successful call. Therefore, for GET operations, a response definition with a status code belonging to the 2XX range (except 204) should have a non-empty content mapping defined using the content property. |
OPENAPI3APIMATIC_L465 | non-empty-response-content-key | Error | Each media type within the content object of a response object must have a non-empty media type key. The media type key represents the content type of the response. |
OpenAPI Callbacks
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3APIMATIC_L500 | callback-only-post-method-allowed | Error | API callbacks are server-initiated notifications sent to a client-specified URL. Only the POST HTTP method is allowed for callback operations. Using any other method is not supported. |
OPENAPI3APIMATIC_L501 | callback-discriminator-property-pointer-missing-request-body-content | Error | The callback discriminator property pointer cannot be resolved because the request body does not have any content defined. Ensure the request body contains valid media type content definitions. |
OPENAPI3APIMATIC_L502 | callback-valid-key | Error | Callback keys must follow valid naming conventions so they can be reliably referenced and processed. |
OPENAPI3APIMATIC_L503 | callback-no-group-assigned-warning | Warning | It is recommended that callbacks are assigned to a callback group using the APIMatic callback group extension. Unassigned callbacks may not be properly categorized in the generated documentation or SDKs. |
OPENAPI3APIMATIC_L505 | callback-discriminator-property-pointer-required | Error | When an event discriminator is defined for a callback group, the propertyPointer field must be specified. This pointer identifies the field in the request body used to differentiate between event types. |
OPENAPI3APIMATIC_L506 | callback-discriminator-property-pointer-invalid-format | Error | The property pointer in the event discriminator must follow a valid JSON pointer format starting with $request.body. An invalid format will prevent the discriminator from correctly identifying the event type field. |
OPENAPI3APIMATIC_L507 | callback-discriminator-property-pointer-invalid-location | Error | The property pointer in the event discriminator must reference a location within the request body. Pointers that reference other locations are not supported for callback event discrimination. |
OPENAPI3APIMATIC_L508 | callback-discriminator-property-pointer-empty-path | Error | The property pointer in the event discriminator must contain a non-empty path after the location prefix $request.body#/. An empty path cannot identify a specific field in the request body. |
OPENAPI3APIMATIC_L509 | callback-discriminator-property-pointer-missing-request-body | Error | The property pointer in the event discriminator references a field in the request body, but the callback operation does not have a request body defined. A request body is required for the discriminator to function. |
OPENAPI3APIMATIC_L510 | callback-discriminator-property-pointer-points-to-valid-property | Error | The property pointer in the event discriminator must reference an existing property in the request body schema. If the pointer does not resolve to a valid property, the event discrimination will fail. |
OPENAPI3APIMATIC_L511 | callback-discriminator-property-pointer-references-string-type | Error | The property referenced by the event discriminator pointer must be of type string. Non-string types cannot be used as discriminator values for identifying different event types. |
OPENAPI3APIMATIC_L512 | callback-discriminator-mapping-value-references-existing-definition | Error | Each value in the event discriminator mapping must reference an existing callback definition. Mapping values that reference non-existent callbacks will prevent proper event type resolution. |
OPENAPI3APIMATIC_L513 | callback-payload-verification-algorithm-required | Error | When payload verification is defined for a callback group, the algorithm field must be specified. This defines the hashing algorithm used to verify the integrity of the callback payload. |
OPENAPI3APIMATIC_L514 | callback-payload-verification-invalid-algorithm | Error | The payload verification algorithm must be one of the supported algorithms. Invalid algorithms will prevent the callback payload verification from being properly configured. |
OPENAPI3APIMATIC_L515 | callback-payload-verification-signature-header-required | Error | When payload verification is defined for a callback group, the signatureHeader field must be specified. This identifies the HTTP header that contains the signature for payload verification. |
OPENAPI3APIMATIC_L517 | callback-payload-verification-valid-digest-encoding | Error | The payload verification digest encoding must be one of the supported encoding formats. Invalid encoding values will prevent proper payload verification configuration. |
OPENAPI3APIMATIC_L518 | callback-payload-verification-digest-encoding-requires-hmac-algorithm | Error | The digestEncoding property in payload verification is only applicable when using HMAC-based algorithms. Using digest encoding with non-HMAC algorithms is not supported. |
OPENAPI3APIMATIC_L519 | callback-payload-verification-valid-message-template | Error | The message template in payload verification must only contain supported placeholders. Invalid placeholders will prevent the message from being properly constructed for signature verification. |
OPENAPI3APIMATIC_L520 | callback-payload-verification-valid-signature-value-template | Error | The signature value template in payload verification must follow the expected format with supported placeholders. Invalid templates will prevent proper signature extraction and verification. |
OPENAPI3APIMATIC_L521 | callback-extension-group-must-exist-when-referenced | Error | When a callback operation references a callback group name, that group must be defined in the x-callback-groups extension at the root level. Referencing a non-existent group will result in an invalid configuration. |
OPENAPI3APIMATIC_L522 | callback-valid-placeholder-delimiter | Error | Placeholders in the payload verification message template must use valid delimiters. Invalid delimiters will prevent proper parsing of the message template. |
OPENAPI3APIMATIC_L523 | callback-discriminator-mapping-value-empty | Error | Each entry in the discriminator mapping must reference a valid callback ID. Mapping values that are empty or missing will prevent proper event discrimination. |
OPENAPI3APIMATIC_L524 | callback-group-non-empty-description | Warning | When a description is provided for a callback group, it must contain a non-empty value. An empty description provides no useful information and should either be removed or populated with meaningful content. |
OpenAPI Tags
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3APIMATIC_L600 | unique-tag | Error | Duplicate tag names have been found, which can lead to ambiguity and confusion in documentation and tooling. Each tag must have a unique name. |
OPENAPI3APIMATIC_L601 | alphabetical-global-tags | Warning (disabled) | Tags defined globally must be in alphabetical order. |
OPENAPI3APIMATIC_L602 | at-least-one-tag-reference | Warning | Each tag should be referenced by one or more operations. |
OPENAPI3APIMATIC_L603 | non-empty-tag-name | Error | A tag object must be assigned a valid non-null and non-empty name. |
OpenAPI References
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3APIMATIC_L630 | non-empty-dollar-ref-path | Error | Path assigned to a $ref must be non-null, non-empty and valid reference path that must be defined within the specification. |
OpenAPI Schemas
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3APIMATIC_L660 | no-equivalent-schema-definitions | Information (disabled) | Schema definitions must be unique, equivalent definitions lead to unnecessarily large specifications. |
OPENAPI3APIMATIC_L661 | no-schema-circular-reference-loop | Error | If a schema definition references another definition (alias or not), the reference must be resolvable and not form any kind of loop. |
OPENAPI3APIMATIC_L662 | no-inline-complex-schema-definition | Warning | A complex schema is one that may use one or more of the following constructs: allOf, anyOf, oneOf, not, properties. Such schema definitions must be added globally in the components/schemas section with a unique name and then referenced throughout the API document with that name or should define title property alongside the properties property. Inline definitions of such schemas are not recommended as for auto-generating SDKs/documentation the names of such schemas are deduced from the parent objects in which they are declared inline. The names deduced this way may not be user-friendly and can conflict with other definitions resulting in name duplication. This behavior can affect your output quality. |
OPENAPI3APIMATIC_L663 | unique-schema-title | Error | Duplicate schema titles have been found, which can lead to confusion and potential conflicts. Each schema within the API specification must have a unique title. |
OPENAPI3APIMATIC_L664 | no-schema-default-for-required-parameter | Warning (disabled) | A default value should not be assigned to a required parameter. Required parameters must be provided with a value during the API call, and assigning a default value may lead to unexpected behavior. Please check the parameter definition in the API specification and remove any default values assigned to required parameters. If a default value is needed, consider making the parameter optional by removing the required flag. |
OPENAPI3APIMATIC_L665 | no-explicit-schema-type-implies-any-type | Warning (disabled) | Schema definitions where the type is not explicitly defined can be of any type. |
OPENAPI3APIMATIC_L666 | int32-schema-format-with-integer-type | Warning | The int32 format is only applicable to schemas with the type set to integer. It seems that the int32 format has been used with an incompatible schema type. |
OPENAPI3APIMATIC_L667 | int64-schema-format-with-integer-type | Warning | The int64 format is only applicable to schemas with the type set to integer. It seems that the int64 format has been used with an incompatible schema type. |
OPENAPI3APIMATIC_L668 | float-schema-format-with-number-type | Warning | The float format is only applicable to schemas with the type set to number. It seems that the float format has been used with an incompatible schema type. |
OPENAPI3APIMATIC_L669 | double-schema-format-with-number-type | Warning | The double format is only applicable to schemas with the type set to number. It seems that the double format has been used with an incompatible schema type. |
OPENAPI3APIMATIC_L670 | byte-schema-format-with-string-type | Warning | The byte format is only applicable to schemas with the type set to string. It seems that the byte format has been used with an incompatible schema type. |
OPENAPI3APIMATIC_L671 | binary-schema-format-with-string-type | Warning | The binary format is only applicable to schemas with the type set to string. It seems that the binary format has been used with an incompatible schema type. |
OPENAPI3APIMATIC_L672 | no-binary-schema-for-operation-parameter | Error (disabled) | The binary format cannot be used with schemas that are being used within operation parameters. |
OPENAPI3APIMATIC_L673 | no-binary-schema-for-json-request-body-content | Error (disabled) | The binary format cannot be used with schemas that are being used with JSON request body content. |
OPENAPI3APIMATIC_L674 | no-binary-schema-for-json-response-content | Error (disabled) | The binary format cannot be used with schemas that are being used with JSON response content. |
OPENAPI3APIMATIC_L675 | date-schema-format-with-string-type | Warning | The date format is only applicable to schemas with the type set to string. It seems that the date format has been used with an incompatible schema type. |
OPENAPI3APIMATIC_L676 | date-time-schema-format-with-string-type | Warning | The date-time format is only applicable to schemas with the type set to string. It seems that the date-time format has been used with an incompatible schema type. |
OPENAPI3APIMATIC_L677 | password-schema-format-with-string-type | Warning | The password format is only applicable to schemas with the type set to string. It seems that the password format has been used with an incompatible schema type. |
OPENAPI3APIMATIC_L678 | string-schema-boundaries-defined | Warning (disabled) | The schema properties for a string should define the pattern, minLength and maxLength attributes. These attributes help to define the constraints on the format and length of the string value. Please check the schema definition in the API specification for the string type and ensure that it has the pattern, minLength, and maxLength attributes defined with appropriate values. |
OPENAPI3APIMATIC_L679 | schema-max-length-cannot-be-less-than-min-length | Warning | The maximum length of a schema cannot be less than the minimum length. In other words, if a minimum length is specified for a schema, the maximum length must be greater than or equal to that minimum length. |
OPENAPI3APIMATIC_L680 | number-boundaries-defined | Warning (disabled) | Numeric schemas should have both a minimum and maximum boundary defined in OpenAPI 3.0 specifications. |
OPENAPI3APIMATIC_L681 | schema-maximum-cannot-be-less-than-minimum | Warning | The maximum value of a schema cannot be less than the minimum value. In other words, if a minimum value is specified for a schema, the maximum value must be greater than or equal to that minimum value. |
OPENAPI3APIMATIC_L682 | object-schema-boundaries-defined | Warning (disabled) | Schemas of type object must define the boundaries of the schema i.e. the maximum number of properties and the minimum number of properties. |
OPENAPI3APIMATIC_L683 | schema-max-properties-cannot-be-less-than-min-properties | Warning | In OpenAPI specifications, if a minimum number of properties is defined for a schema, then a maximum number of properties should also be defined, and the maximum number of properties should be equal to or greater than the minimum number of properties. |
OPENAPI3APIMATIC_L684 | pre-defined-required-schema-property | Error | The properties listed in the required list of a schema must be pre-defined in the schema properties. |
OPENAPI3APIMATIC_L685 | non-empty-schema-properties-key | Error | In OpenAPI specifications, a schema's property keys should be non-empty strings. Empty property keys can cause issues when working with schemas and can lead to errors when the specification is used to generate code or documentation. |
OPENAPI3APIMATIC_L687 | no-schema-default-for-required-property | Warning (disabled) | Required properties should not have a default value defined as this can lead to unwanted behavior therefore, these must be removed. |
OPENAPI3APIMATIC_L689 | array-schema-boundaries-defined | Warning (disabled) | In OpenAPI specifications, array boundaries should be defined for schemas that include array data types. |
OPENAPI3APIMATIC_L690 | schema-max-items-cannot-be-less-than-min-items | Warning | In OpenAPI specifications, for schemas that include array data types, the maximum number of items allowed in the array must be greater than or equal to the minimum number of items allowed in the array. |
OPENAPI3APIMATIC_L692 | no-inline-enum-schema-definition | Warning | Either define a title property alongside the enum property or the schema definitions must be added globally in the components/schemas section with a unique name and then referenced throughout the API document with that name. Inline definitions of enum schemas are not recommended as for auto-generating SDKs/documentation the names of such schemas are deduced from the parent objects in which they are declared inline. The names deduced this way may not be user-friendly and can conflict with other definitions resulting in name duplication. This behavior can affect your output quality. |
OPENAPI3APIMATIC_L693 | at-least-one-item-in-schema-enum-list | Error | Enum list must not be empty as it is used to define a set of valid values for the schema. An empty enum list can cause ambiguity in the definition of acceptable values. |
OPENAPI3APIMATIC_L694 | unique-schema-enum-items | Error | If property enum is specified in the schema object, it must consist of only unique items in the list. |
OPENAPI3APIMATIC_L695 | same-schema-enum-item-type | Error | The data type of each item defined in an enumeration list must conform to the type defined for the schema object. |
OPENAPI3APIMATIC_L696 | non-empty-schema-enum-value | Error | All items of an enumeration list must have a non-empty and non-null value. They represent the set of possible values of the enumeration and, therefore, cannot be empty or null. |
OPENAPI3APIMATIC_L697 | no-schema-circular-inheritance | Error | Circular references within schemas are not allowed. A circular reference occurs when one schema references another schema that, in turn, references the original schema, creating a circular dependency. Circular references can lead to issues with data modeling, validation, and may cause infinite loops in processing. |
OPENAPI3APIMATIC_L698 | single-discriminator-declaration-in-schema-hierarchy | Error | A discriminated schema should not redefine the discriminator property. The discriminator property is defined at the root level of the schema and serves to differentiate between subtypes. Redefining the discriminator property within subtypes can lead to inconsistencies and conflicts. |
OPENAPI3APIMATIC_L699 | non-primitive-any-of-schemas-in-polymorphism | Error | It is not allowed to use the schemas with primitive types in anyOf list when discriminator property is defined alongside anyOf. This refers to polymorphism which is the ability of a schema to represent different types or subtypes in the presence of discriminator. |
OPENAPI3APIMATIC_L700 | non-primitive-one-of-schemas-in-polymorphism | Error | It is not allowed to define the schemas with primitive types in oneOf list when discriminator property is defined alongside oneOf. This refers to polymorphism which is the ability of a schema to represent different types or subtypes in the presence of discriminator. |
OPENAPI3APIMATIC_L701 | no-base-schema-property-re-declaration | Warning | When using the allOf keyword to combine multiple schemas, each schema should define unique properties. It appears that there is a duplicate property that already exists in one of the schemas defined within the allOf array. |
OPENAPI3APIMATIC_L702 | required-string-type-for-discriminator-schema-property | Error | The discriminator property is used to differentiate between different subtypes within a schema. This discriminator property, used for polymorphism, must be of type string. |
OPENAPI3APIMATIC_L703 | no-items-property-with-non-array-type | Warning | When the items property is present in a schema, the type must be explicitly defined as array. Using the items property with schemas that have explicitly defined non-array types (such as string, number, object, boolean, etc.) can lead to issues with schema validation, code generation, and API documentation tools. |
OpenAPI Discriminators
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3APIMATIC_L800 | non-empty-discriminator-property-name | Error | The discriminator property name should be non-empty and non-null. |
OPENAPI3APIMATIC_L801 | pre-defined-schema-property-for-discriminator | Error | The discriminator property (indicated by propertyName) should either be defined directly in the same schema in which discriminator is used or be defined in oneOf/anyOf options. |
OPENAPI3APIMATIC_L802 | non-empty-discriminator-mapping-key | Error | In OpenAPI specifications, the discriminator mapping key must be a non-empty string. The discriminator mapping key is used to map the discriminator value to a schema definition. |
OPENAPI3APIMATIC_L803 | unique-discriminator-mapping-key | Error | The discriminator mapping keys defined in the discriminator object must be unique. |
OPENAPI3APIMATIC_L804 | non-empty-discriminator-mapping-value | Error | Discriminator mapping value must specify the name or the reference to the globally defined schema to which the discriminator value needs to be mapped to. This information is useful for deserialization purposes. Therefore, the value must be non-null, non-empty and must reference to a globally defined schema. |
OPENAPI3APIMATIC_L805 | pre-defined-discriminator-mapping-value-schema | Error | In OpenAPI specifications, when using a discriminator to distinguish between different schemas, each schema must be defined in the specification. Each schema referenced in the discriminator mapping must be defined in the specification to ensure that the schema is properly defined and can be used correctly. |
OPENAPI3APIMATIC_L806 | discriminator-mapping-value-for-each-one-of-schema | Error | Discriminator mapping values indicate possible schemas that a payload can be deserialized into, based on the discriminator property. Therefore, it is expected that a mapping value is provided for each of the schemas involved in the oneOf list. A missing value for any schema may cause deserialization issues in the generated code. |
OPENAPI3APIMATIC_L807 | discriminator-mapping-value-for-each-any-of-schema | Error | Discriminator mapping values indicate possible schemas that a payload can be deserialized into, based on the discriminator property. Therefore, it is expected that a mapping value is provided for each of the schemas involved in the anyOf list. A missing value for any schema may cause deserialization issues in the generated code. |
OpenAPI XML
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3APIMATIC_L840 | required-xml-name-in-parameter-schema | Error | In OpenAPI specifications, when using XML for the parameter schema, it is required to specify the XML name. However, for array non-wrapped cases, the name does not need to be directly specified in the schema XML. In such cases, it will be present in the inner items schema. |
OPENAPI3APIMATIC_L841 | required-xml-name-in-request-body-content-schema | Error | In OpenAPI specifications, when using XML for the request body content schema, the XML name is required to be specified. However, for array non-wrapped cases, the name does not need to be directly specified in the schema XML. In such cases, it will be present in the inner items schema. |
OPENAPI3APIMATIC_L842 | required-xml-name-in-response-content-schema | Error | In OpenAPI specifications, when using XML for the response content schema, the XML name is required to be specified. However, for array non-wrapped cases, the name does not need to be directly specified in the schema XML. In such cases, it will be present in the inner items schema. |
OPENAPI3APIMATIC_L843 | required-xml-name-in-schema-property | Error | In OpenAPI specifications, when using XML for schema properties, the XML name is required to be specified. An XML name should be specified for schema properties to ensure that the schema is properly defined and can be used correctly. |
OPENAPI3APIMATIC_L844 | no-xml-name-in-non-wrapped-array-schema | Warning | In OpenAPI specifications, when using XML for array schemas, there are two ways to serialize an array: as a 'wrapped' array, where each element of the array is a child element of a container element, or as a 'non-wrapped' array, where each element of the array is a sibling element of the other elements. When using non-wrapped array schemas, specifying an XML name is forbidden. This rule enforces the requirement that an XML name cannot be specified for non-wrapped array schemas to ensure that the schema is properly defined and can be used correctly. |
OPENAPI3APIMATIC_L845 | xml-wrapped-only-for-array-schema-type | Error | In OpenAPI specifications, XML serialization (wrapped) can be used to describe how to serialize and deserialize XML documents. The wrapped style applies to array schema types and defines how XML elements are named when representing arrays. This rule enforces the requirement that the wrapped style can only be used with array schema types to ensure that the schema is properly defined and can be used correctly. |
OPENAPI3APIMATIC_L846 | only-schema-primitive-type-for-xml-attribute-property | Error | When declaring schema properties as XML attributes, only primitive types are allowed. Non-primitive types, such as object types or arrays, are not permitted as XML attribute properties. |
OPENAPI3APIMATIC_L847 | only-schema-properties-can-be-xml-attributes | Error | Only schema properties can be marked as XML attributes while the root schema can only be marked as XML element. |
OPENAPI3APIMATIC_L848 | no-namespace-for-schema-xml-attribute-property | Error | Namespace is provided for a property declared as an XML attribute which is not allowed. |
OpenAPI Security Schemes
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3APIMATIC_L870 | non-empty-api-key-security-parameter-name | Error | The name property is used to identify the parameter or header that contains the API key. The name property of an API key security scheme must not be empty or null. |
OPENAPI3APIMATIC_L871 | non-empty-scheme-of-http-security-scheme | Error | The scheme property specifies the HTTP authentication scheme to be used, such as basic, bearer, etc. The scheme property of an HTTP security scheme must not be empty or null. |
OPENAPI3APIMATIC_L872 | required-non-empty-additional-header-name | Error | A non-null, non-empty, user-friendly name must be provided for the additional header in x-additional-headers APIMatic extension. |
OPENAPI3APIMATIC_L873 | non-conflicting-api-key-header-and-additional-header | Error | An additional header cannot have the same name as the API key, this leads to unwanted behavior and conflicts. |
OpenAPI OAuth 2.0 Flows
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3APIMATIC_L910 | pre-defined-oauth2-authorization-server-in-server-configuration | Error | The authorization server referenced inside the OAuth 2.0 authentication definition must be pre-defined in the server configuration of the API. |
OPENAPI3APIMATIC_L911 | pre-defined-oauth2-token-server-in-server-configuration | Error | The access token server referenced inside the OAuth 2.0 authentication definition must be pre-defined in the server configuration of the API. |
OPENAPI3APIMATIC_L912 | non-empty-oauth-flow-scopes-key | Error | The scope key is used to define the scopes or permissions associated with the OAuth flow. A non-empty scope key must be provided in all OAuth scope definitions. |
OPENAPI3APIMATIC_L913 | unique-oauth-flow-scopes-key | Error | The scope keys defined in the OAuth flow object must be unique. |
OpenAPI Security Requirements
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3APIMATIC_L930 | at-least-one-security-mechanism-applied | Warning | APIs that require some form of authentication must define the security schemes used, in the global Components Object using the securitySchemes property and apply these security schemes to the endpoints that require authentication. This will ensure that the requests that require authentication are authenticated properly. |
OPENAPI3APIMATIC_L931 | unique-security-requirement | Warning | Each security requirement object represents a unique combination of security schemes that need to be satisfied for an API operation. The security list should not contain duplicate security requirement objects. |
OPENAPI3APIMATIC_L932 | unique-security-requirement-scopes | Error | Each security requirement scope within a security scheme represents a unique permission or access level. Therefore, duplicate entries for security requirement scopes are not allowed. |
OPENAPI3APIMATIC_L933 | pre-defined-security-requirement-scope-in-security-scheme | Error | A security requirement must only use pre-defined scopes from the security scheme scope definitions. |
OpenAPI Vendor Extensions
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3APIMATIC_L950 | supported-vendor-extension | Warning | APIMatic supports certain vendor extensions which are loaded at the time of importing API description files containing these extensions. These include APIMatic specific extensions as well that are used for configuring products like Code Generation, Transformer, etc. All other extensions will be ignored or may not work as expected. |
OPENAPI3APIMATIC_L951 | no-additional-apimatic-vendor-extension-property | Warning | APIMatic specific extensions that are used for configuring products like Code Generation, Transformer, etc. do not support any additional vendor extension properties which will be ignored or may not work as expected. |
Miscellaneous
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3APIMATIC_L970 | supported-response-code | Warning | If multiple responses are disabled via import settings provided in the APIMatic Metadata file, only response definitions in responses belonging to status code ranges 200-208 and 400-599 will be imported. Those outside the supported range will be ignored automatically during import/transformations in APIMatic. |
Pagination
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3APIMATIC_L1000 | valid-pagination-type | Error | The pagination type defined for the response must be one of the supported types: "offset", "page", "cursor", or "link". Any other value is considered invalid. |
OPENAPI3APIMATIC_L1001 | non-empty-pagination-result | Error | The result field within the pagination object must be a valid, non-empty JSON pointer string. It should point to an array field in the API response that contains the paginated results. |
OPENAPI3APIMATIC_L1002 | pagination-result-points-to-array | Error | The result field in the pagination object must be a valid JSON pointer that references an array field in the API response. Pointers targeting non-array fields are not supported and will result in an invalid pagination configuration. |
OPENAPI3APIMATIC_L1003 | valid-pagination-json-pointer | Error | The JSON pointer must reference a valid location within the request or response. Examples of valid pointers include: $response.body, $response.body#/data/prop, and $request.query#/offset. |
OPENAPI3APIMATIC_L1004 | pagination-pointer-points-valid-property | Error | The JSON pointer must reference an existing property within the request or response structure. If it points to a property that does not exist, the pagination configuration is considered invalid. |
OPENAPI3APIMATIC_L1005 | non-empty-pagination-input | Error | The input field in the pagination object must be a valid, non-empty JSON pointer string. It should reference a field in the API request that provides the pagination input, such as an offset, page number, or cursor value. |
OPENAPI3APIMATIC_L1006 | non-empty-pagination-output | Error | The output field in the cursor pagination object must be a valid, non-empty JSON pointer string. It should reference a field in the API response that provides the pagination output, such as a next cursor value. |
OPENAPI3APIMATIC_L1007 | cursor-input-cursor-output-types-should-match | Error | The input and output fields in a cursor-based pagination object must have matching schema types. For example, if the input field is of type string, the output field must also be of type string. |
OPENAPI3APIMATIC_L1008 | non-empty-pagination-next | Error | The next field in a link-based pagination object must be a valid, non-empty JSON pointer string. It should reference a field in the API response that provides the URL to the next page of results. |
OPENAPI3APIMATIC_L1009 | link-pagination-next-must-be-string | Error | In link-based pagination, the next field must be a string containing the URL to the next page of results. Any other type is considered invalid. |
OPENAPI3APIMATIC_L1010 | pagination-input-must-point-to-integer-property | Error | For both offset-based and page-based pagination strategies, the input field must point to a property of type integer. This value typically represents the starting offset or page number and must be a valid integer to ensure correct pagination behavior. |
OPENAPI3APIMATIC_L1011 | pagination-type-required | Error | Every pagination extension must specify a type field indicating the pagination strategy. Supported values are "offset", "page", "cursor", and "link". Without a type, the pagination configuration cannot be validated or applied. |
OpenAPI Webhooks
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3APIMATIC_L1030 | webhook-only-post-method-allowed | Error | Webhooks are server-initiated notifications sent to a client-specified URL. Only the POST HTTP method is allowed for webhook operations. Using any other method is not supported. |
OPENAPI3APIMATIC_L1031 | webhook-discriminator-property-pointer-missing-request-body-content | Error | The webhook discriminator property pointer cannot be resolved because the request body does not have any content defined. Ensure the request body contains valid media type content definitions. |
OPENAPI3APIMATIC_L1032 | webhook-valid-key | Error | Webhook keys must be non-empty and follow naming conventions. Invalid or empty webhook keys may cause issues during code generation or API documentation. |
OPENAPI3APIMATIC_L1033 | webhook-no-group-assigned | Warning | It is recommended that webhooks are assigned to a webhook group using the APIMatic webhook group extension. Unassigned webhooks may not be properly categorized in the generated documentation or SDKs. |
OPENAPI3APIMATIC_L1035 | webhook-discriminator-property-pointer-required | Error | When an event discriminator is defined for a webhook group, the propertyPointer field must be specified. This pointer identifies the field in the request body used to differentiate between event types. |
OPENAPI3APIMATIC_L1036 | webhook-discriminator-property-pointer-invalid-format | Error | The property pointer in the event discriminator must follow a valid JSON pointer format starting with /. An invalid format will prevent the discriminator from correctly identifying the event type field. |
OPENAPI3APIMATIC_L1037 | webhook-discriminator-property-pointer-invalid-location | Error | The property pointer in the event discriminator must reference a location within the request body. Pointers that reference other locations are not supported for webhook event discrimination. |
OPENAPI3APIMATIC_L1038 | webhook-discriminator-property-pointer-empty-path | Error | The property pointer in the event discriminator must contain a non-empty path after the location prefix. An empty path cannot identify a specific field in the request body. |
OPENAPI3APIMATIC_L1039 | webhook-discriminator-property-pointer-missing-request-body | Error | The property pointer in the event discriminator references a field in the request body, but the webhook operation does not have a request body defined. A request body is required for the discriminator to function. |
OPENAPI3APIMATIC_L1040 | webhook-discriminator-property-pointer-points-to-valid-property | Error | The property pointer in the event discriminator must reference an existing property in the request body schema. If the pointer does not resolve to a valid property, the event discrimination will fail. |
OPENAPI3APIMATIC_L1041 | webhook-discriminator-property-pointer-references-string-type | Error | The property referenced by the event discriminator pointer must be of type string. Non-string types cannot be used as discriminator values for identifying different event types. |
OPENAPI3APIMATIC_L1042 | webhook-discriminator-mapping-value-references-existing-definition | Error | Each value in the event discriminator mapping must reference an existing webhook definition. Mapping values that reference non-existent webhooks will prevent proper event type resolution. |
OPENAPI3APIMATIC_L1043 | webhook-payload-verification-algorithm-required | Error | When payload verification is defined for a webhook group, the algorithm field must be specified. This defines the hashing algorithm used to verify the integrity of the webhook payload. |
OPENAPI3APIMATIC_L1044 | webhook-payload-verification-invalid-algorithm | Error | The payload verification algorithm must be one of the supported algorithms. Invalid algorithms will prevent the webhook payload verification from being properly configured. |
OPENAPI3APIMATIC_L1045 | webhook-payload-verification-signature-header-required | Error | When payload verification is defined for a webhook group, the signatureHeader field must be specified. This identifies the HTTP header that contains the signature for payload verification. |
OPENAPI3APIMATIC_L1047 | webhook-payload-verification-valid-digest-encoding | Error | The payload verification digest encoding must be one of the supported encoding formats. Invalid encoding values will prevent proper payload verification configuration. |
OPENAPI3APIMATIC_L1048 | webhook-payload-verification-digest-encoding-requires-hmac-algorithm | Error | The digestEncoding property in payload verification is only applicable when using HMAC-based algorithms. Using digest encoding with non-HMAC algorithms is not supported. |
OPENAPI3APIMATIC_L1049 | webhook-payload-verification-valid-message-template | Error | The message template in payload verification must only contain supported placeholders. Invalid placeholders will prevent the message from being properly constructed for signature verification. |
OPENAPI3APIMATIC_L1050 | webhook-payload-verification-valid-signature-value-template | Error | The signature value template in payload verification must follow the expected format with supported placeholders. Invalid templates will prevent proper signature extraction and verification. |
OPENAPI3APIMATIC_L1051 | webhook-extension-group-must-exist-when-referenced | Error | When a webhook operation references a webhook group name, that group must be defined in the x-webhook-groups extension at the root level. Referencing a non-existent group will result in an invalid configuration. |
OPENAPI3APIMATIC_L1052 | webhook-valid-placeholder-delimiter | Error | Placeholders in the payload verification message template must use valid delimiters. Invalid delimiters will prevent proper parsing of the message template. |
OPENAPI3APIMATIC_L1053 | webhook-discriminator-mapping-value-empty | Error | Each entry in the discriminator mapping must reference a valid webhook ID. Mapping values that are empty or missing will prevent proper event discrimination. |
OPENAPI3APIMATIC_L1054 | webhook-group-non-empty-description | Warning | When a description is provided for a webhook group, it must contain a non-empty value. An empty description provides no useful information and should either be removed or populated with meaningful content. |
Learn more
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.
OpenAPI v3 APIMatic Syntax Linting
Linting checks performed by APIMatic on provided OpenAPI v3 file to check its conformance to recommended syntax practices for better API consumption.