Define & Validate APIsValidation RulesetsAPIMatic Rulesets
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.
| Property | Value |
|---|---|
| Ruleset ID | apimatic-post-processing-validation |
| Code prefix | APIMATICPOSTPROCESS_V |
| Type | Validation |
| Default severity | Warning |
| Rule system | Semantic |
| Rules | 47 |
Rules marked (disabled) are turned off by default, so they don't report issues.
Server Configuration
| Code | Rule | Severity | What it checks |
|---|---|---|---|
APIMATICPOSTPROCESS_V001 | server-parameter-cannot-be-array | Warning | Server URL parameters cannot be declared as arrays. Only primitive types like string, number or string/number enumeration types are allowed. Array type server parameters will be automatically converted to non-array entities. |
APIMATICPOSTPROCESS_V002 | server-parameter-cannot-be-map-object | Warning | Server URL parameters cannot be declared as maps or objects. Only primitive types like string, number or string/number enumeration types are allowed. Map/object type server parameters will be automatically converted to primitive entities. |
APIMATICPOSTPROCESS_V003 | server-parameter-cannot-be-constant | Warning | Server URL parameter cannot be declared as read-only or constant. Such parameters will be automatically marked as non-constant entities. |
Authentication
| Code | Rule | Severity | What it checks |
|---|---|---|---|
APIMATICPOSTPROCESS_V101 | valid-oauth-2-parameter-format | Warning | The format specified for an OAuth 2.0 parameter, indicating how the parameter should be sent, must be one of the allowed formats for that authentication parameter e.g. form and query are the only allowed formats for the grant_type parameter. |
APIMATICPOSTPROCESS_V102 | supported-oauth-2-parameter-format | Warning | The format specified for an OAuth 2.0 parameter, indicating how the parameter should be sent, must be one of the allowed formats for that authentication parameter. If, however, we have no parameter entry beforehand indicating its allowed formats, then all formats specified by user for such a parameter will be ignored. |
APIMATICPOSTPROCESS_V103 | non-empty-authentication-scheme-name | Warning | Authentication scheme key name must be non-null and non-empty. |
APIMATICPOSTPROCESS_V104 | non-null-non-empty-applied-authentication-scheme-name | Warning | When an authentication scheme is applied, the authentication scheme name must be non-null, non-empty and correspond with the name of a predefined authentication scheme. If that is not the case, the authentication will not be considered as an applicable form of an authentication option. |
APIMATICPOSTPROCESS_V105 | unique-authentication-option-name | Warning | The name assigned to an authentication option in a list must be unique. If that is not the case, the authentication option is automatically assigned a unique name. |
APIMATICPOSTPROCESS_V106 | unique-authentication-options | Warning | An authentication option in a list of options must be unique. If that is not the case, it will be automatically removed. The uniqueness of an authentication option is determined by uniqueness of the authentication schemes that need to be applied as part of this option, required scope values, etc. |
APIMATICPOSTPROCESS_V107 | authentication-scheme-referenced-by-auth-option | Warning | A valid authentication option must reference at least one or more predefined authentication schemes depending on the option type. A single authentication option type can only reference one authentication scheme while a group authentication option can consist of two or more authentication schemes. An option that does not reference any authentication scheme will be considered an invalid option and automatically removed from the list of available options. |
APIMATICPOSTPROCESS_V108 | unique-authentication-schemes-in-group-auth-option | Warning | A group authentication option is one that makes use of multiple authentication schemes to complete the authentication. It must not consist of duplicate authentication schemes and if any are found they will be automatically removed. |
APIMATICPOSTPROCESS_V109 | two-or-more-authentication-schemes-in-group-auth-option | Information | A group authentication option makes use of multiple authentication schemes to complete the authentication. Therefore, it must consist of at least two or more authentication schemes. If it consists of only a single authentication scheme, its type will be automatically changed from 'Group' to 'Single'. |
Endpoints
| Code | Rule | Severity | What it checks |
|---|---|---|---|
APIMATICPOSTPROCESS_V201 | endpoint-group-globally-defined | Warning (disabled) | An endpoint can only be placed inside an endpoint group which is pre-defined under the API level endpoint groups definition. If that is not the case, the missing group definition will be automatically generated and added in the global endpoint groups. |
APIMATICPOSTPROCESS_V202 | unique-endpoint-scopes | Warning | The required scopes of an endpoint must be unique. |
Endpoint Parameters
| Code | Rule | Severity | What it checks |
|---|---|---|---|
APIMATICPOSTPROCESS_V251 | valid-parameter-primitive-type | Warning (disabled) | Some types like "Binary", "Void" and "Dynamic" are not applicable to parameters and, therefore, will be auto-converted to their equivalent valid types. |
APIMATICPOSTPROCESS_V252 | predefined-endpoint-path-template-parameter | Information | All path/template parameters present in the endpoint relative route must have a corresponding definition in the endpoint. |
APIMATICPOSTPROCESS_V253 | valid-template-parameter-format | Warning | Path/Template parameter present in the endpoint relative route must have "Template" set as its format in its corresponding endpoint definition. |
Endpoint Responses
| Code | Rule | Severity | What it checks |
|---|---|---|---|
APIMATICPOSTPROCESS_V301 | valid-response-primitive-type | Warning (disabled) | Some types like "File" and "Object" are not applicable to responses and, therefore, will be auto-converted to their equivalent valid types. |
APIMATICPOSTPROCESS_V302 | non-empty-response-content-media-type | Warning | Response content media type must be non-null and non-empty. |
APIMATICPOSTPROCESS_V303 | sorted-error-codes | Warning | Error codes must be sorted in an ascending/increasing order. If they are found to be out of order, they will be sorted automatically during the post-processing. |
Types
| Code | Rule | Severity | What it checks |
|---|---|---|---|
APIMATICPOSTPROCESS_V351 | native-primitive-type | Warning | A component in SDL (an internal format to which the user API specification docuemnt is converted) can only use primitive types which are supported by APIMatic. A non-native primitive type will be converted to APIMatic's supported primitive types. |
APIMATICPOSTPROCESS_V352 | dynamic-entities-cannot-be-arrays | Warning | If an entity has the type "Dynamic", it cannot be declared as an array. If it is marked as an array, it will be automatically converted to a non-array entity. |
APIMATICPOSTPROCESS_V353 | pre-defined-model | Warning | A model referenced by any component must be pre-defined in the global custom types. If that is not the case, then for components that support "Object" or "Dynamic" primitive types, the component referencing the undefined model will fall back to one of these types. |
APIMATICPOSTPROCESS_V354 | type-combinator-cases-meta-count-must-match | Warning | The metadata provided for the various cases of the type combinators (anyOf, oneOf or not) must match the total number of cases present. If that is not the case, the invalid metadata information will be automatically removed. |
APIMATICPOSTPROCESS_V355 | non-empty-global-type-combinators-reference-name | Warning | If a global type combinators reference name is specified, the name must be non-null and non-empty. |
Global Types/Models
| Code | Rule | Severity | What it checks |
|---|---|---|---|
APIMATICPOSTPROCESS_V401 | valid-numeric-enum-default-value | Warning | Default values of all enumeration model fields must be set. In case they are missing or invalid and the enumeration model is of numeric type, we may infer the default values ourselves. |
APIMATICPOSTPROCESS_V402 | required-enum-field-default-value | Warning | All enumeration model fields must have a default value set, that represents one of the allowed values for the enumeration entity. If the default value is missing, the enumeration field name will be assigned as the default value of that field. |
APIMATICPOSTPROCESS_V403 | required-discriminator-field | Warning | If a discriminator is specified for a model, the model must have a corresponding discriminator field/property defined in its fields. If it is found to be missing, a default discriminator field definition will be automatically added. |
APIMATICPOSTPROCESS_V404 | valid-custom-type-field-primitive-type | Warning (disabled) | Some types like "File", "Void" and "Dynamic" are not applicable to model fields and, therefore, will be auto-converted to their equivalent valid types. |
APIMATICPOSTPROCESS_V491 | non-empty-global-type-combinators-key | Warning | The unique key/name specified for the global type combinators entry must be non-null and non-empty. If that is not the case, the invalid entry will be automatically removed from the global type combinators definitions. |
APIMATICPOSTPROCESS_V492 | global-type-combinators-id-exists | Information (disabled) | The id of a global type combinators entry uniquely identifies this entry from others in the same list as well as from the names of the global models in the Custom Types list. If the id is not specified, it will automatically be generated. |
APIMATICPOSTPROCESS_V493 | unique-global-type-combinators-id | Warning (disabled) | The id of a global type combinators entry must uniquely identify this entry from others in the same list as well as from the names of the global models in the Custom Types list. If that is not the case, the id will automatically be assigned a unique value. |
APIMATICPOSTPROCESS_V494 | non-empty-discriminator-mapping-key | Warning | Possible discriminator values provided as keys of the discriminator mapping information must be non-null and non-empty. If that is not the case, this entry will be treated as invalid and removed from the discriminator mapping definition. |
APIMATICPOSTPROCESS_V495 | non-null-non-empty-discriminator-mapping-value | Warning | Discriminator mapping value represents the concrete type to which the discriminator value needs to be mapped to. This information is useful for deserialization purposes. If this mapping value is null or empty, the mapping information is considered incomplete and the entry for it will automatically be removed from the discriminator mapping definition. |
Examples
| Code | Rule | Severity | What it checks |
|---|---|---|---|
APIMATICPOSTPROCESS_V501 | valid-example-value | Warning | The sample value provided must be valid according to the type definition of the component to which it belongs. |
APIMATICPOSTPROCESS_V502 | example-value-restrictions | Warning | The sample value provided must obey all restrictions placed in the corresponding type definition. |
APIMATICPOSTPROCESS_V503 | no-example-for-error-with-no-model | Warning | An example must not be set for a error response that has no error model linked to it. |
APIMATICPOSTPROCESS_V504 | unique-example-ids | Warning | The ids assigned to examples provided for a component must be unique. Duplicate ids will be renamed. |
APIMATICPOSTPROCESS_V505 | non-empty-non-null-example-id | Warning | All examples provided for a component must be assigned unique, non-empty and non-null ids. |
APIMATICPOSTPROCESS_V506 | valid-example-external-value | Warning | The external URL provided for example, from which the example value is retrieved, must be a valid publicly-accessible URL. Otherwise, the URL will be ignored. |
APIMATICPOSTPROCESS_V507 | required-example-value-or-external-url | Warning | An example entry from the multiple examples list must have either an example value set or an alternate external URL from which the example value can be fetched. Otherwise, the example entry will be ignored. |
APIMATICPOSTPROCESS_V508 | supported-default-value | Warning | For some types, default values are currently not supported and will be ignored. |
APIMATICPOSTPROCESS_V509 | sample-value-no-white-spaces | Warning | A sample value must not contain any leading or trailing white-space characters. |
APIMATICPOSTPROCESS_V510 | valid-boolean-value | Warning | A boolean entity can only have one of the two possible values: 'true' or 'false'. Any other variants e.g. 0, 1, y, etc. are not allowed and will either be ignored or converted to a valid variant. |
Miscellaneous
| Code | Rule | Severity | What it checks |
|---|---|---|---|
APIMATICPOSTPROCESS_V601 | name-no-white-spaces | Warning | Name of an entity must not contain any leading or trailing white-space characters. |
APIMATICPOSTPROCESS_V602 | description-no-white-spaces | Warning | Description of an entity must not contain any leading or trailing white-space characters. |
APIMATICPOSTPROCESS_V603 | required-api-version | Warning | The API version is a required property, which cannot be null or empty. If it is not provided, it is set as 1.0. |
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.
APIMatic Post-Processing Validation For Code Generation
APIMatic post-processes a user-provided API specification document and automatically fixes some common issues that can impact code generation. This validation helps inform users about these issues and the fixes performed.