Define & Validate APIsValidation RulesetsOpenAPI Rulesets
OpenAPI v3 Linting for APIMatic Code Generation
Linting checks performed by APIMatic on provided OpenAPI v3 file to check its conformance to recommended practices for better code generation experience.
| Property | Value |
|---|---|
| Ruleset ID | openapi-v3-codegen-linting |
| Code prefix | OPENAPI3CODEGEN_L |
| Type | Linting |
| Default severity | Warning |
| Rule system | Semantic |
| Rules | 65 |
Rules marked (disabled) are turned off by default, so they don't report issues.
OpenAPI Root Information
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3CODEGEN_L001 | required-paths | Error | The API specification must define at least one endpoint path. Endpoint paths represent the URLs that clients can use to interact with the API. |
OpenAPI Info
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3CODEGEN_L050 | maximum-info-title-length | Warning | The title assigned to the API in the Info Object using the title property must not exceed 50 characters. Longer titles can compromise on user-friendliness. In addition to that, the title is used for naming various components generated during code generation including files where very long names are forbidden. |
OPENAPI3CODEGEN_L051 | info-title-exceeds-maximum-allowed-length | Error | The title assigned to the API in the Info Object must not exceed 100 characters. Titles exceeding this limit will cause failures in Code Generation, Docs Generation, and Portal Generation. |
OpenAPI Servers
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3CODEGEN_L090 | environment-name-uses-title-case | Warning (disabled) | The environment name in the server configuration of the API should be defined in TitleCase. |
OPENAPI3CODEGEN_L091 | maximum-environment-name-length | Warning | The length of the environment name should not exceed 50 characters, as longer names can lead to problems in code generation and negatively impact user-friendliness. |
OPENAPI3CODEGEN_L092 | required-servers | Error | OpenAPI root object must specify at least one server using the servers property. Information about the servers provide connectivity information related to a target server of the API. Empty servers defaults to localhost which can prevent your end-users from consuming your API. |
OPENAPI3CODEGEN_L093 | at-least-one-server-in-servers-list | Error | The OpenAPI specification requires that an API definition must include a list of servers that are used to access the API. This rule enforces the requirement that the servers array must contain at least one server definition. |
OPENAPI3CODEGEN_L094 | server-name-uses-title-case | Warning (disabled) | The server name in the server configuration of the API should be defines in TitleCase. |
OPENAPI3CODEGEN_L095 | maximum-server-name-length | Warning | The length of the server name should not exceed 50 characters, as longer names can lead to problems in code generation and negatively impact user-friendliness. |
OPENAPI3CODEGEN_L096 | server-url-not-example-dot-com | Error | The domain name example.com is reserved by the Internet Engineering Task Force (IETF) for use in documentation and examples, and it should not be used as an actual domain name in production environments. This rule enforces the requirement that server URLs in an OpenAPI specification should not point to example.com, in order to avoid any potential confusion or conflicts with the reserved domain name. |
OPENAPI3CODEGEN_L097 | maximum-server-variables-key-length | Warning | The keys used for server variables in an OpenAPI specification should not exceed 50 characters in length. Server variables are used to define variables in the server URL, and their names should be concise and meaningful to ensure that they are easily understandable by developers. Exceeding the limit of 50 characters can make the server variables difficult to read and understand, and can cause issues in Code Generation, Portal Generation or Transformations. |
OPENAPI3CODEGEN_L098 | maximum-server-parameter-name-length | Warning | The length of the server parameter name shouldn't exceed 50 characters, as longer names can lead to problems in code generation and negatively impact user-friendliness. |
OPENAPI3CODEGEN_L099 | environment-name-exceeds-maximum-allowed-length | Error | The length of the environment name must not exceed 100 characters. Names exceeding this limit will cause failures in Code Generation, Docs Generation, and Portal Generation. |
OPENAPI3CODEGEN_L100 | server-name-exceeds-maximum-allowed-length | Error | The length of the server name must not exceed 100 characters. Names exceeding this limit will cause failures in Code Generation, Docs Generation, and Portal Generation. |
OPENAPI3CODEGEN_L101 | server-variables-key-exceeds-maximum-allowed-length | Error | The keys used for server variables must not exceed 100 characters. Keys exceeding this limit will cause failures in Code Generation, Docs Generation, and Portal Generation. |
OPENAPI3CODEGEN_L102 | server-parameter-name-exceeds-maximum-allowed-length | Error | The length of the server parameter name must not exceed 100 characters. Names exceeding this limit will cause failures in Code Generation, Docs Generation, and Portal Generation. |
OpenAPI Components
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3CODEGEN_L130 | unique-case-insensitive-schema-component-key | Error | A duplicate schema component key has been detected, indicating that there are multiple schemas with the same key defined in the components section. Since keys are compared in case-insensitive manner, it is important that each schema component in the API specification has a unique key. |
OPENAPI3CODEGEN_L132 | schema-component-key-uses-pascal-case | Warning (disabled) | To enhance the readability and maintain consistency, it is recommended that the keys defined in the components object's schemas are formatted using PascalCase. PascalCase is a naming convention in which each word in a phrase is capitalized, without spaces or underscores between them. This convention helps to make the keys stand out more clearly and allows for easier identification and understanding of the different components. By adhering to this convention, developers can also avoid potential errors and improve the overall quality of the code. |
OPENAPI3CODEGEN_L133 | no-articles-in-schema-component-key | Warning (disabled) | The schema name defined in the OpenAPI Component object should be concise and to the point. To maintain consistency, avoid using articles (such as a, an, or the) in schema names as they are not necessary and can make the name longer than needed. Long or overly descriptive schema names can impact readability and increase the potential for errors when working with the API definition. |
OPENAPI3CODEGEN_L134 | no-coordinating-conjunctions-in-schema-component-key | Warning (disabled) | When defining schemas in the component object, the name of the schema should be descriptive and concise. Avoid using coordinating conjunctions such as and, but or for in the schema name. This helps keep the schema name clear and to the point, making it easier to understand and use. |
OPENAPI3CODEGEN_L135 | singular-key-of-non-array-schema-component | Warning (disabled) | Schema key names for non-array schemas should be singular to provide clear and concise naming. Plural schema names can cause confusion, so it's important to use singular nouns to describe the data type accurately. For example, user instead of users. |
OPENAPI3CODEGEN_L136 | no-enum-postfix-in-enum-schema-component-key | Warning (disabled) | Enumeration schema key defined in components/schemas section should not contain Enum postfix (case-insensitive). |
OPENAPI3CODEGEN_L137 | maximum-schema-component-key-length | Warning | The length of the schema key should not exceed 50 characters, which is considered a best practice. Excessive schema key lengths can create readability issues and can cause issues in code generation. Keeping them concise helps to ensure that they are easily understandable and convey their purpose clearly. |
OPENAPI3CODEGEN_L138 | schema-component-key-exceeds-maximum-allowed-length | Error | The length of the schema key must not exceed 100 characters. Keys exceeding this limit will cause failures in Code Generation, Docs Generation, and Portal Generation. |
OpenAPI Paths
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3CODEGEN_L160 | at-least-one-path-item | Error | An OpenAPI specification must contain at least one path. The paths property of an OpenAPI specification defines the available endpoints of the API, and each endpoint must have a unique path. An API with no paths defined is considered invalid and cannot be used by clients to make requests. |
OpenAPI Path Items
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3CODEGEN_L170 | at-least-one-path-item-operation | Error | Each path defined in an OpenAPI specification must include one or more operation objects. An operation object defines an API operation, such as GET, POST, PUT, DELETE, etc., and contains information such as the request and response schema, parameters, and security requirements. |
OPENAPI3CODEGEN_L171 | path-item-optional-parameters-after-required-parameters | Warning | For code generation purposes, it is recommended that optional parameters should be defined at the end of the Path Item parameters list and not before or between required parameters. |
OPENAPI3CODEGEN_L172 | unique-case-insensitive-path-item-parameter-name | Error | A duplicate parameter name has been detected, indicating that there are multiple parameters with the same name defined in the path items object. Since parameter names are compared in a case-insensitive manner, it is important that each parameter name in a path item object has a unique name. |
OPENAPI3CODEGEN_L173 | maximum-path-item-parameter-name-length | Warning | Parameter name within the path item length must not be equal to or exceed 50 characters. |
OPENAPI3CODEGEN_L174 | path-item-parameter-name-exceeds-maximum-allowed-length | Error | Parameter name within the path item must not exceed 100 characters. Names exceeding this limit will cause failures in Code Generation, Docs Generation, and Portal Generation. |
OpenAPI Operations
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3CODEGEN_L192 | unique-case-insensitive-operation-id | Error (disabled) | A duplicate operation id has been detected, indicating that there are multiple operations with the same operation id defined in the path items object. Since operation ids are compared in a case-insensitive manner, it is essential that each operation in a path item object has a unique id. |
OPENAPI3CODEGEN_L193 | operation-id-uses-pascal-case | Warning (disabled) | OperationId define in the Operation object must be defined in PascalCase format. |
OPENAPI3CODEGEN_L194 | no-articles-in-operation-id | Warning (disabled) | The OperationId is a unique identifier for an operation, and it should reflect the purpose or functionality of the operation. Using articles like a, an, the in the OperationId can make it unnecessarily long and difficult to read. Therefore, it is recommended to avoid using articles in the OperationId. |
OPENAPI3CODEGEN_L195 | no-coordinating-conjunctions-in-operation-id | Warning (disabled) | The OperationId field in the OpenAPI specification is used to uniquely identify an operation. To ensure consistency and clarity, it is recommended that the OperationId should not contain coordinating conjunctions like and, but, for. These words can make the name of the operation unnecessarily long and can make it harder to read and understand. |
OPENAPI3CODEGEN_L196 | maximum-operation-id-length | Warning | An Operation ID is a unique identifier for an operation object in an OpenAPI specification. It is used to generate client-side code and provide human-readable documentation. This rule ensures that the length of the Operation ID in the API definition does not exceed 50 characters, which is considered a best practice. |
OPENAPI3CODEGEN_L197 | unique-case-insensitive-operation-tag-name | Error | A duplicate operation tag name has been detected, indicating that there are multiple operation tags with the same name. Since operation tag names are compared in a case-insensitive manner, it is crucial that each operation has a unique tag. |
OPENAPI3CODEGEN_L198 | operation-tag-name-uses-title-case | Warning (disabled) | Tag name define in the Operation Object should be defined in TitleCase. |
OPENAPI3CODEGEN_L199 | no-articles-in-operation-tag-name | Warning (disabled) | The operation tag name should not contain articles like a, an, or the. These words can make the name of the operation unnecessarily long and can make it harder to read and understand. |
OPENAPI3CODEGEN_L200 | no-coordinating-conjunctions-in-operation-tag-name | Warning (disabled) | Operation tag names in OpenAPI should not contain coordinating conjunctions such as and, but, or for to keep the tag name concise and meaningful. |
OPENAPI3CODEGEN_L201 | maximum-operation-tag-name-length | Warning | Tag name length define in the operation object should not exceed 50 characters. |
OPENAPI3CODEGEN_L202 | operation-optional-parameters-after-required-parameters | Warning | For code generation purposes, it is recommended that optional parameters should be defined at the end of the Operation Object parameters list and not before or between required parameters. |
OPENAPI3CODEGEN_L203 | unique-case-insensitive-operation-parameter-name | Error | A duplicate parameter name has been detected, indicating that there are multiple parameters with the same name defined in the operation object. Sine parameter names are compared in a case-insensitive manner, it is important that each parameter name in an operation object has a unique name. |
OPENAPI3CODEGEN_L204 | maximum-operation-parameter-name-length | Warning | In an OpenAPI specification, operation parameters are used to describe inputs for an API operation. The parameter name is a unique identifier for a parameter and should be descriptive of the parameter's purpose. This rule ensures that the length of operation parameter names does not exceed 50 characters, which is considered a best practice. |
OPENAPI3CODEGEN_L205 | operation-id-exceeds-maximum-allowed-length | Error | The Operation ID must not exceed 100 characters. IDs exceeding this limit will cause failures in Code Generation, Docs Generation, and Portal Generation. |
OPENAPI3CODEGEN_L206 | operation-tag-name-exceeds-maximum-allowed-length | Error | Tag name length defined in the operation object must not exceed 100 characters. Names exceeding this limit will cause failures in Code Generation, Docs Generation, and Portal Generation. |
OPENAPI3CODEGEN_L207 | operation-parameter-name-exceeds-maximum-allowed-length | Error | The operation parameter name must not exceed 100 characters. Names exceeding this limit will cause failures in Code Generation, Docs Generation, and Portal Generation. |
OpenAPI Callbacks
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3CODEGEN_L540 | callback-missing-request-body | Warning | Callback operations should include a request body definition to describe the payload that will be sent to the callback URL. A missing request body may lead to incomplete or unusable callback definitions. |
OpenAPI Tags
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3CODEGEN_L580 | unique-case-insensitive-global-tag-name | Error | A duplicate tag name has been detected, indicating that there are multiple tag objects with the same name defined. Since tag names are compared in a case-insensitive manner, it is crucial that each tag object has a unique name. |
OPENAPI3CODEGEN_L581 | tag-name-uses-title-case | Warning (disabled) | When defining tags for OpenAPI, use TitleCase, which means capitalizing the first letter of each word in the tag except for conjunctions, prepositions, and articles. This makes the tags more readable. |
OPENAPI3CODEGEN_L582 | no-articles-in-tag-name | Warning (disabled) | The tag name should not contain articles like a, an, or the. These words can make the name of the operation unnecessarily long and can make it harder to read and understand. |
OPENAPI3CODEGEN_L583 | no-coordinating-conjunctions-in-tag-name | Warning (disabled) | Tag names in OpenAPI should not contain coordinating conjunctions such as and, but, or for to keep the tag name concise and meaningful. |
OPENAPI3CODEGEN_L584 | maximum-tag-name-length | Warning | Tag name length should not exceed 50 characters. |
OPENAPI3CODEGEN_L585 | tag-name-exceeds-maximum-allowed-length | Error | Tag name length must not exceed 100 characters. Names exceeding this limit will cause failures in Code Generation, Docs Generation, and Portal Generation. |
OpenAPI Schemas
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3CODEGEN_L610 | unique-case-insensitive-schema-title | Error | A duplicate schema title has been detected, indicating that there are multiple schemas with the same title. Since titles are compared in a case-insensitive manner, it is important that each title in an schema object is unique. |
OPENAPI3CODEGEN_L617 | maximum-schema-title-length | Warning | The title assigned to the Schema Object using the title property must not exceed 50 characters. Longer titles can compromise on user-friendliness. In addition to that, the title is used for naming various components generated during code generation where it is possible that very long names are forbidden. Details should go into the description field instead. |
OPENAPI3CODEGEN_L618 | required-schema-properties-with-object-type | Warning | In an OpenAPI document, if a schema object has the type 'object', it must also contain a 'properties' property that defines the object's properties. This is required to accurately describe the structure of the object and enable proper validation. |
OPENAPI3CODEGEN_L620 | non-conflicting-schema-property-name-and-schema-key | Warning | Schema keys and property names should not conflict with each other. Each schema should have a unique key that serves as its identifier, and property names within the schema should also be unique. Conflicts occur when a schema key is the same as a property name, leading to ambiguity and potential issues with the interpretation of the schema. |
OPENAPI3CODEGEN_L621 | non-conflicting-schema-property-name-and-schema-title | Warning | Schema title and property names should not conflict with each other. Each schema should have a unique title that serves as its identifier, and property names within the schema should also be unique. Conflicts occur when a schema title is the same as a property name, leading to ambiguity and potential issues with the interpretation of the schema. |
OPENAPI3CODEGEN_L622 | unique-case-insensitive-schema-property-name | Error | A duplicate schema property name has been detected, indicating that there are multiple schema properties with the same name. Since schema property names are compared in a case-insensitive manner, it is important that each property in an schema object has a unique name. |
OPENAPI3CODEGEN_L623 | maximum-schema-property-name-length | Warning | In an OpenAPI specification, the property keys define the properties of a schema object. This rule ensures that the length of the property keys does not exceed 50 characters, which is considered a best practice. Excessive schema property key lengths can create readability issues and can cause issues in code generation. Keeping them concise helps to ensure that they are easily understandable and convey their purpose clearly. |
OPENAPI3CODEGEN_L624 | schema-title-exceeds-maximum-allowed-length | Error | The title assigned to the Schema Object must not exceed 100 characters. Titles exceeding this limit will cause failures in Code Generation, Docs Generation, and Portal Generation. |
OPENAPI3CODEGEN_L625 | schema-property-name-exceeds-maximum-allowed-length | Error | The schema property name must not exceed 100 characters. Names exceeding this limit will cause failures in Code Generation, Docs Generation, and Portal Generation. |
OPENAPI3CODEGEN_L629 | enum-elements-count-matches-schema-enum-items-count | Warning | The x-enum-elements extension is used to provide additional information or metadata for each enum item. The x-enum-elements extension, when used, should have an object count that matches the number of enum items defined in the schema. |
OpenAPI Security Requirements
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3CODEGEN_L783 | security-options-meta-count-matches-security-items-count | Warning | You can extend the security information you apply globally or at operation level by using the x-security-options-meta extension. It can help you provide more details for each of the security options available. However, the number of items inside the x-security-options-meta extension must match the number of items inside the security list. If that is not the case, the extension data will be ignored automatically during import/transformations in APIMatic. |
OpenAPI Webhooks
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3CODEGEN_L1000 | webhook-missing-request-body | Warning | Webhook operations should include a request body definition to describe the payload that will be sent to the webhook URL. A missing request body may lead to incomplete or unusable webhook definitions. |
Learn more
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.
OpenAPI v3 Syntax Linting for APIMatic Code Generation
Linting checks performed by APIMatic on provided OpenAPI v3 file to check its conformance to recommended syntax practices for better code generation experience.