Define & Validate APIsValidation RulesetsAPIMatic Rulesets
APIMatic Validation for Code Generation
APIMatic performs some preliminary checks on the user-provided API specification document to ensure that it meets the basic requirements for generating a valid output during SDK and Portal generation.
| Property | Value |
|---|---|
| Ruleset ID | apimatic-codegen-validation |
| Code prefix | APIMATICCODEGEN_V |
| Type | Validation |
| Default severity | Error |
| Rule system | Semantic |
| Rules | 87 |
Name Conventions
| Code | Rule | Severity | What it checks |
|---|---|---|---|
APIMATICCODEGEN_V001 | valid-name-conventions | Error | For successful Code Generation, the name must only use letters, numbers, underscores and dashes. It must not contain any leading/trailing white-space characters. Names are often used for naming the files generated as part of the code generation process, so, any forbidden file name characters are not allowed. |
APIMATICCODEGEN_V002 | valid-name-length-conventions | Warning | Name length must not be equal to or exceed 50 characters. |
APIMATICCODEGEN_V003 | name-exceeds-maximum-allowed-length | Error | Name length must not exceed 100 characters. Names exceeding this limit will cause failures in Code Generation, Docs Generation, and Portal Generation. |
XML Attributes
| Code | Rule | Severity | What it checks |
|---|---|---|---|
APIMATICCODEGEN_V006 | valid-xml-namespace-conventions | Error | An XML namespace must be a non-null, non-empty and well-formed URI. |
APIMATICCODEGEN_V007 | unique-element-xml-node-names-in-model | Error | The XML node names assigned to fields marked as XML elements in a model must be unique. |
APIMATICCODEGEN_V008 | unique-attribute-xml-node-names-in-model | Error | The XML node names assigned to fields marked as XML attributes in a model must be unique. |
APIMATICCODEGEN_V009 | no-dynamic-type-usage-with-xml | Error | If API uses XML serialization/deserialization, then use of "Dynamic" type components is not supported. |
Authentication
| Code | Rule | Severity | What it checks |
|---|---|---|---|
APIMATICCODEGEN_V021 | no-space-in-scope-value | Error | Scope values must not contain spaces. |
APIMATICCODEGEN_V022 | oauth1-authentication-not-allowed | Error | OAuth 1.0 authentication methods are deprecated and not supported. Use OAuth 2.0 or other modern authentication schemes instead. |
Server Configuration
| Code | Rule | Severity | What it checks |
|---|---|---|---|
APIMATICCODEGEN_V031 | valid-api-base-url | Error | The Base URL specified for the API must be a non-empty non-null absolute URL. |
Endpoints
| Code | Rule | Severity | What it checks |
|---|---|---|---|
APIMATICCODEGEN_V041 | atleast-one-endpoint | Error | An API must contain atleast one endpoint for Code Generation. |
APIMATICCODEGEN_V042 | unique-endpoint-group-name | Error | Endpoint group names must be unique. |
APIMATICCODEGEN_V043 | non-conflicting-endpoint-name | Error | Endpoint names must be unique when letter casing and symbols are ignored. |
APIMATICCODEGEN_V044 | non-conflicting-method-name | Error | Method names in an endpoint group must be unique when letter casing and symbols are ignored. |
APIMATICCODEGEN_V045 | valid-method-name-conventions | Error | Method names must use letters, numbers, spaces, underscores and dashes only. The name must start with a letter. |
Endpoint Parameters
| Code | Rule | Severity | What it checks |
|---|---|---|---|
APIMATICCODEGEN_V071 | unique-endpoint-parameter-name | Error | The name of a parameter in an endpoint must be unique when all the parameter names of an endpoint are compared in a case-insensitive manner. |
APIMATICCODEGEN_V073 | no-complex-types-in-non-body-parameters | Error | Use of complex model types for non-body parameters (template, header) is currently not supported. Only enumeration or primitive types are allowed. |
APIMATICCODEGEN_V074 | no-array-header-parameters | Error | A header parameter cannot be set as an array. |
APIMATICCODEGEN_V075 | no-array-file-form-parameters | Error | An array of "File" type parameters is currently not supported. |
Endpoint Responses
| Code | Rule | Severity | What it checks |
|---|---|---|---|
APIMATICCODEGEN_V101 | response-mapping-required-field | Error | A Data Field or an Error Field must be specified in the response mapping. |
APIMATICCODEGEN_V102 | valid-response-mapping-field-elements | Error | A response mapping field element must not be null. Only empty/whitespace strings are allowed. |
APIMATICCODEGEN_V103 | response-mapping-data-field-value-for-complex-types | Error | A Data Field is only allowed for endpoints for which the response has a "Dynamic" type or a complex model/custom type. |
APIMATICCODEGEN_V104 | 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. |
APIMATICCODEGEN_V105 | 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. |
APIMATICCODEGEN_V106 | 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 aren't supported and will result in an invalid pagination configuration. |
APIMATICCODEGEN_V107 | 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. |
APIMATICCODEGEN_V108 | pagination-pointer-points-valid-field | Error | The JSON pointer must reference an existing field within the request or response structure. If it points to a field that doesn't exist, the pagination configuration is considered invalid. |
APIMATICCODEGEN_V109 | 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. |
APIMATICCODEGEN_V110 | 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. |
APIMATICCODEGEN_V111 | 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. |
APIMATICCODEGEN_V112 | 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. |
APIMATICCODEGEN_V113 | 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. |
APIMATICCODEGEN_V114 | pagination-input-must-be-integer | Error | For both offset-based and page-based pagination strategies, the input field must be of type integer. This value typically represents the starting offset or page number and must be a valid integer to ensure correct pagination behavior. |
Global Types/Models
| Code | Rule | Severity | What it checks |
|---|---|---|---|
APIMATICCODEGEN_V131 | unique-model-names | Error | Names of globally defined custom types/models must be unique. |
APIMATICCODEGEN_V132 | valid-enum-field-name-conventions | Error | Names assigned to fields of an enumeration model must not contain special characters. |
APIMATICCODEGEN_V133 | non-conflicting-model-and-endpoint-group-names | Error | If controller and model postfixing is disabled, similar model names and endpoint group names can cause conflicts in code generation, therefore, the names of both entities must be kept unique overall. |
APIMATICCODEGEN_V134 | model-atleast-one-field | Warning | A structure/exception model must consist of at least one field/property declaration. |
APIMATICCODEGEN_V135 | unique-field-name | Error | Names of fields in a model must be unique. |
APIMATICCODEGEN_V136 | non-conflicting-model-and-field-name | Warning | A model's name must not conflict with names of its fields. This is because some languages do not allow member names to be the same name as their enclosing type. The accessor or variable names may be changed to address this problem. |
Test Cases
| Code | Rule | Severity | What it checks |
|---|---|---|---|
APIMATICCODEGEN_V161 | non-conflicting-test-case-name | Error | Names of test cases of an endpoint must not contain any conflicts. |
APIMATICCODEGEN_V162 | predefined-test-input-parameter | Error | A test case input parameter must correspond to a pre-defined parameter in the endpoint in which the test case is defined. |
APIMATICCODEGEN_V163 | valid-input-parameter-test-value | Error | The test value provided for the input parameter in a test case must be valid and correspond with the parameter type definition. |
APIMATICCODEGEN_V164 | input-parameter-test-value-restrictions | Error | The test value provided for the input parameter in a test case must obey all restrictions placed in the corresponding parameter type definition. |
APIMATICCODEGEN_V165 | optional-query-parameters-test-case | Warning | Test case must not contain undeclared query parameters if endpoint does not allow optional query parameters. |
APIMATICCODEGEN_V166 | optional-field-parameters-test-case | Warning | Test case must not contain undeclared field parameters if endpoint does not allow optional field parameters. |
APIMATICCODEGEN_V167 | valid-test-case-expected-status | Error | The expected status of a test case must be a valid HTTP status code or range and its corresponding response definition must be present in the endpoint responses. |
APIMATICCODEGEN_V168 | allowed-test-case-body-match-mode | Error | The body match mode specified in the test case (if not set to None) must be valid and applicable to the type(s) of the response(s) indicated by the expected status. |
APIMATICCODEGEN_V169 | valid-test-case-expected-body-value | Error | The value provided for the expected response body in a test case must be valid and correspond with the type definition(s) of the response(s) indicated by the expected status. |
APIMATICCODEGEN_V170 | test-case-expected-body-value-restrictions | Error | The value provided for the expected response body in a test case must obey all restrictions placed in the corresponding response type definition(s). |
CodeGen Settings
| Code | Rule | Severity | What it checks |
|---|---|---|---|
APIMATICCODEGEN_V251 | valid-request-timeout-codegen-setting | Error | The request timeout specified in the code generation settings must be a positive number. |
APIMATICCODEGEN_V252 | valid-php-composer-package-name-codegen-setting | Error | PHP Composer package name must match the naming rules specified in the composer schema file. |
APIMATICCODEGEN_V253 | valid-php-namespace-name-codegen-setting | Error | PHP namespace name must not contain forbidden characters or use invalid format. |
APIMATICCODEGEN_V254 | java-group-id-codegen-setting-match-naming-rules | Error | Java Group ID must match the naming rules specified in maven guides. |
APIMATICCODEGEN_V255 | java-artifact-id-codegen-setting-match-naming-rules | Error | Java Artifact ID must match the naming rules specified in maven guides. |
APIMATICCODEGEN_V256 | controller-postfix-codegen-setting-naming-conventions | Error | Controller postfix must use letters, numbers, underscore and dashes only. |
Miscellaneous
| Code | Rule | Severity | What it checks |
|---|---|---|---|
APIMATICCODEGEN_V501 | valid-error-template-key | Error | The key of an error template entry must be a valid error HTTP status code/range (e.g. 4XX, 500) or set to 0 to represent default/undeclared errors. |
APIMATICCODEGEN_V502 | valid-error-template-message | Error | Value of an error template entry must be a valid string message, with support for expression templates. A template must start and end with curly braces {} and contain a valid expression in between. The templates are filled with actual data at runtime. Allowed template expression placeholders include: {$statusCode}, {$response.header.<headerKey>}, {$response.body<#JsonPointer>}. If {$response.header.<headerKey>} placeholder is used, <headerKey> must be replaced with a valid response header name. <#JsonPointer> in the {$response.body<#JsonPointer>} placeholder is an optional segment that can be used to access a particular part of a JSON response body. If used, it must follow valid JSON pointer syntax. |
Webhooks
| Code | Rule | Severity | What it checks |
|---|---|---|---|
APIMATICCODEGEN_V521 | discriminator-property-pointer-required | Error | When a discriminator section exists in webhook or callback configuration, the propertyPointer field MUST be present and non-empty to enable event type discrimination. |
APIMATICCODEGEN_V522 | discriminator-property-pointer-points-to-valid-property | Error | The property that propertyPointer references MUST exist in the parent request body schema to enable proper event type discrimination for webhooks and callbacks. |
APIMATICCODEGEN_V523 | discriminator-property-pointer-references-string-type | Error | The property that propertyPointer references MUST be of string type to allow proper event matching and discrimination logic for webhooks and callbacks. |
APIMATICCODEGEN_V524 | discriminator-mapping-value-references-existing-definition | Error | Every ID referenced in discriminator mapping values MUST correspond to an existing webhook or callback definition in the respective section. |
APIMATICCODEGEN_V525 | payload-verification-custom-algorithm-name-required | Warning | When a custom algorithm is specified in payload verification configuration, a name field should be provided to identify the custom verifier implementation. |
APIMATICCODEGEN_V526 | payload-verification-algorithm-required | Error | When payloadVerification exists in webhook or callback configuration, the algorithm field MUST be specified with a valid value. |
APIMATICCODEGEN_V527 | payload-verification-signature-header-required | Error | When payloadVerification exists in webhook or callback configuration, the signatureHeader field MUST be specified to indicate which header contains the signature. |
APIMATICCODEGEN_V528 | extension-group-must-exist-when-referenced | Error | When webhook or callback operations reference an extension group, the corresponding x-webhooks or x-callbacks extension MUST exist in the API specification. |
APIMATICCODEGEN_V529 | payload-verification-valid-digest-encoding | Error | The digestEncoding field in payload verification must use one of the accepted values: 'hex', 'base64', or 'base64url'. If no value is specified, 'hex' is used as the default. |
APIMATICCODEGEN_V530 | payload-verification-valid-message-template | Error | The messageTemplate field must only use supported placeholders. Webhook templates support {$request.body}, {$method}, {$request.header.<HeaderName>}, {$request.body#/property}. Callback templates support additional placeholders including {$url}, {$request.path}, {$request.query.<ParamName>}. If no value is specified, '{$request.body}' is used as the default. |
APIMATICCODEGEN_V531 | payload-verification-valid-signature-value-template | Error | The signatureValueTemplate field must contain the {digest} placeholder to insert the computed digest. If no value is specified, '{digest}' is used as the default. |
APIMATICCODEGEN_V532 | webhook-only-post-method-allowed | Error | Webhooks must use only the POST HTTP method. Other HTTP methods like PUT aren't supported for webhook operations. |
APIMATICCODEGEN_V533 | valid-placeholder-delimiter | Error | The template string contains placeholders (for example '{$request.body}', '{$method}') that must be separated by exactly one single-character delimiter such as ':', '-', or '_'. Multiple characters, missing delimiters, or multi-character strings between placeholders aren't allowed. This ensures consistent and predictable template formatting. |
APIMATICCODEGEN_V534 | callback-url-expression-validation | Error | The callback URL expression must be valid and reference an existing string-type property. Callback URLs can be specified as runtime expressions (pointers), relative URLs, or absolute URLs, but any referenced properties must exist and be of string type. |
APIMATICCODEGEN_V535 | webhook-no-group-assigned-warning | Warning | This webhook doesn't have an x-webhook-group extension specified. While not required, assigning webhooks to groups enables better organization and discriminator functionality. |
APIMATICCODEGEN_V536 | callback-no-group-assigned-warning | Warning | This callback doesn't have an x-callback-group extension specified. While not required, assigning callbacks to groups enables better organization and discriminator functionality. |
APIMATICCODEGEN_V537 | webhook-missing-request-body | Warning | Webhooks typically require a request body parameter to receive event data from external services. A missing request body may indicate incomplete webhook configuration or prevent proper event handling. |
APIMATICCODEGEN_V538 | callback-missing-request-body | Warning | Callbacks typically require a request body parameter to send event data to external services. A missing request body may indicate incomplete callback configuration or prevent proper event notification. |
APIMATICCODEGEN_V541 | callback-only-post-method-allowed | Error | Callbacks must use only the POST HTTP method. Other HTTP methods like PUT, GET, or DELETE aren't supported for callback operations. |
APIMATICCODEGEN_V542 | webhook-valid-name | Error | Webhook names must follow valid naming conventions. Names should contain only alphanumeric characters, underscores, and hyphens, and must not start with numbers or special characters. |
APIMATICCODEGEN_V543 | callback-valid-name | Error | Callback names must follow valid naming conventions. Names should contain only alphanumeric characters, underscores, and hyphens, and must not start with numbers or special characters. |
APIMATICCODEGEN_V544 | discriminator-property-pointer-invalid-format | Error | The property pointer must follow the format 'location#/path'. It should contain exactly one '#' character separating the location from the JSON pointer path. The Property pointer should point to the root level string property in the request body |
APIMATICCODEGEN_V545 | discriminator-property-pointer-invalid-location | Error | The property pointer location must be 'request.body' for discriminator configuration. Other locations aren't supported for event discrimination. |
APIMATICCODEGEN_V546 | discriminator-property-pointer-empty-path | Error | The JSON pointer path part of the property pointer can't be empty and must reference valid field names. Array indices and empty segments aren't allowed. |
APIMATICCODEGEN_V547 | discriminator-property-pointer-missing-request-body | Error | The endpoint doesn't have a request body parameter, but the discriminator property pointer references 'request.body'. A request body parameter is required for discriminator functionality. |
APIMATICCODEGEN_V548 | callback-duplicate-id-warning | Warning | Duplicate callback IDs detected in the API specification. When multiple callbacks share the same ID, only the first occurrence will be used and subsequent duplicates will be ignored during processing. |
APIMATICCODEGEN_V549 | callback-missing-request-body-with-mapping | Error | This callback is assigned to a callback group that has discriminator mappings, but the callback itself doesn't have a request body parameter. Since discriminator functionality relies on request body content for event type determination, the callback can't be removed without breaking the discriminator mappings. |
APIMATICCODEGEN_V550 | webhook-missing-request-body-with-mapping | Error | This webhook is assigned to a webhook group that has discriminator mappings, but the webhook itself doesn't have a request body parameter. Since discriminator functionality relies on request body content for event type determination, the webhook can't be removed without breaking the discriminator mappings. |
APIMATICCODEGEN_V551 | payload-verification-invalid-algorithm | Error | The algorithm specified in the payload verification configuration isn't supported. Payload verification requires either HMAC-SHA256 or HMAC-SHA512 algorithms to ensure secure message signing and verification. Other algorithms aren't supported by the current implementation. |
APIMATICCODEGEN_V552 | payload-verification-digest-encoding-requires-hmac-algorithm | Error | The digest encoding configuration (hex, base64, or base64url) can only be used with HMAC-based algorithms (HMAC-SHA256 or HMAC-SHA512). The current algorithm doesn't support digest encoding options. |
Learn more
APIMatic Process Validation
The rules in this ruleset help verify whether certain processes in APIMatic are functioning correctly or not or highlight any user-specific/internal issues that are blocking those processes from progressing. Some examples of processes include validation, import, export or transformations of API specifications, etc.
APIMatic Post-Processing Validation
APIMatic post-processes a user-provided API specification document and automatically fixes some common issues. This validation mainly informs users about these issues and the fixes performed.