Define & Validate APIsValidation RulesetsAPIMatic Rulesets
APIMatic Preliminary Validation
APIMatic performs some preliminary validation checks on the user-provided API specification document to ensure that it meets the basic requirements for generating a valid output from any of the APIMatic products including API Transformer, SDK/Portal generation, etc.
| Property | Value |
|---|---|
| Ruleset ID | apimatic-preliminary-validation |
| Code prefix | APIMATICPRE_V |
| Type | Validation |
| Default severity | Error |
| Rule system | Semantic |
| Rules | 102 |
API
| Code | Rule | Severity | What it checks |
|---|---|---|---|
APIMATICPRE_V001 | non-null-api | Error | The API to validate must not be null or empty. |
APIMATICPRE_V002 | unique-role-ids | Error | Role IDs specified in the API role definitions must be unique. |
APIMATICPRE_V003 | non-conflicting-auth-and-additional-header | Error | Additional or global headers apply to all endpoints of the API regardless of whether any authentication schemes apply to those endpoints or not. Therefore, a header already defined as an authentication parameter should not be added as part of additional headers as well, or vice versa. |
Server Configuration
| Code | Rule | Severity | What it checks |
|---|---|---|---|
APIMATICPRE_V031 | predefined-default-environment | Error | The default environment specified in the server configuration of the API must have a corresponding definition in the server configuration environments. |
APIMATICPRE_V032 | unique-environment | Error | The environments defined in the server configuration of the API must have unique names. |
APIMATICPRE_V033 | predefined-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. |
APIMATICPRE_V034 | unique-server | Error | The servers defined for an environment in the server configuration of the API must have unique names. |
APIMATICPRE_V035 | same-environment-server-set | 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. |
APIMATICPRE_V036 | required-server-url | Error | A server definition must specify a non-empty, non-null and absolute URL path. |
Server Configuration Parameters
| Code | Rule | Severity | What it checks |
|---|---|---|---|
APIMATICPRE_V046 | predefined-server-template-parameter | Error | A template parameter referenced by a server must have a corresponding definition in the server configuration parameters. |
APIMATICPRE_V047 | unique-server-parameter | Error | The server parameters defined in the server configuration of the API must have unique names. |
APIMATICPRE_V048 | 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. |
APIMATICPRE_V049 | required-server-parameter-default-value | Error | Server parameter definition in the server configuration of the API must specify a non-empty non-null default value. |
APIMATICPRE_V050 | valid-server-parameter-default-value | Error | The default value specified in the server parameter definition must be valid according to the type definition of this parameter. |
APIMATICPRE_V051 | 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. |
APIMATICPRE_V052 | server-parameter-cannot-be-map-object | Error | Server URL parameters cannot be declared as maps or objects. Only primitive types like string, number or string/number enumeration types are allowed. |
APIMATICPRE_V053 | server-parameter-cannot-be-constant | Error | Server URL parameter cannot be declared as read-only or constant. |
Authentication
| Code | Rule | Severity | What it checks |
|---|---|---|---|
APIMATICPRE_V061 | required-authentication-parameters | Error | For some authentication types like "Custom Field", "Custom Query" and "Custom Header", one or more corresponding authentication parameters must be defined. |
APIMATICPRE_V062 | authentication-parameters-not-required | Error | For some authentication types like those tied to OAuth 1.0, authentication parameters must not be specified. |
APIMATICPRE_V063 | required-jwt-authentication-parameters | Error | For JWT authentication, the following three parameters must be defined: JWTHeaderName, JWTAcquireURL, JWTDestroyURL |
APIMATICPRE_V064 | required-scope-name | Error | A non-empty, non-null scope name must be provided in each authentication scope definition. This name is meant to be a more user-friendly and code-friendly name as compared to the corresponding scope value. |
APIMATICPRE_V065 | required-scope-value | Error | A non-empty and non-null scope value must be provided in all authentication scope definitions. |
APIMATICPRE_V066 | unique-scope-name | Error | Scope names must be unique among all authentication scope definitions. |
APIMATICPRE_V067 | predefined-oauth-2-server | Error | The authorization server or access token server referenced inside the OAuth 2.0 authentication definition must be pre-defined in the server configuration of the API. |
APIMATICPRE_V068 | required-oauth-2-endpoint-url | Error | The URL specified for an OAuth 2.0 endpoint must be a valid non-null, non-empty path relative to the OAuth server. |
APIMATICPRE_V069 | valid-oauth-2-parameter-format | Error | 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. |
APIMATICPRE_V070 | valid-authentication-scheme-name | Error | Authentication scheme key name must be non-null, non-empty and use only letters, numbers, dashes, underscores or dots. |
APIMATICPRE_V071 | authentication-scheme-referenced-by-auth-option | Error | 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 authentication option. |
APIMATICPRE_V072 | non-null-non-empty-applied-authentication-scheme-name | Error | When an authentication scheme is applied, the authentication scheme name must be non-null and non-empty. |
APIMATICPRE_V073 | pre-defined-authentication-scheme | Error | When an authentication scheme is applied, the authentication scheme name must be non-null, non-empty and correspond with the name of a globally defined authentication scheme. |
APIMATICPRE_V074 | unique-authentication-option-name | Error | The name assigned to an authentication option in a list must be unique. |
APIMATICPRE_V075 | default-scope-exists-in-scopes-list | Error | x-default-scopes should only include scopes that are explicitly defined in the OAuth scopes list. This ensures consistency and prevents unauthorized or undefined access levels. |
Endpoints
| Code | Rule | Severity | What it checks |
|---|---|---|---|
APIMATICPRE_V101 | predefined-endpoint-server | Error | Endpoint must use a pre-defined server from the API specification's server configuration. |
APIMATICPRE_V102 | valid-endpoint-relative-route | Error | Endpoint route must be a relative path to the base server URL and begin with a leading forward slash "/". It must also consist of valid path segments. |
APIMATICPRE_V103 | endpoint-group-name-conventions | Error | Name assigned to an endpoint group must be non-null and non-empty. |
APIMATICPRE_V104 | predefined-endpoint-scopes | Error | An endpoint must only use pre-defined scopes from the authentication scope definitions. |
APIMATICPRE_V105 | unique-endpoint-scopes | Error | The required scopes of an endpoint must be unique. |
Endpoint Parameters
| Code | Rule | Severity | What it checks |
|---|---|---|---|
APIMATICPRE_V201 | predefined-endpoint-path-template-parameter | Error | All path/template parameters present in the endpoint relative route must have a corresponding definition in the endpoint. |
APIMATICPRE_V202 | valid-template-parameter-format | Error | Path/Template parameter present in the endpoint relative route must have "Template" set as its format in its corresponding endpoint definition. |
APIMATICPRE_V203 | no-body-form-parameters-in-non-body-http-methods | Error | HTTP methods like GET do not support a request body therefore, such endpoints should not contain parameter definitions of format "Body" or "Form". |
APIMATICPRE_V204 | no-optional-field-parameters-in-non-body-http-methods | Error | HTTP methods like GET do not support a request body therefore, such endpoints cannot allow optional field parameters through the "HasOptionalFieldParams" flag. |
APIMATICPRE_V205 | no-xml-request-body-in-non-body-http-methods | Error | HTTP methods like GET do not support a request body therefore, such endpoints cannot allow XML body requests. |
APIMATICPRE_V206 | required-body-parameter-definition-for-xml-request-endpoint | Error | An explicit endpoint body parameter definition must be present if XML requests are enabled for the endpoint. |
APIMATICPRE_V207 | form-and-body-parameters-cannot-coexist | Error | If an endpoint contains a body parameter, form parameters or optional field parameters are not allowed. |
APIMATICPRE_V208 | multiple-body-parameters | Error | Unless the "WrapBodyInObject" flag is enabled, an endpoint must contain only one body parameter definition. |
APIMATICPRE_V209 | valid-parameter-primitive-type | Error | Some types like "Binary", "Void" and "HttpResponse" are not applicable to parameters and, therefore, should not be used in parameter definitions. |
APIMATICPRE_V210 | valid-dynamic-type-parameter-format | Error | For parameters, type "Dynamic" can only be used for body/form parameters. |
APIMATICPRE_V211 | valid-file-type-parameter-formats | Error | File type can only be used for a parameter with format set as "Body" or "Form". |
APIMATICPRE_V212 | constant-parameter-cannot-be-optional | Error | Constant parameters cannot be declared optional. |
Endpoint Responses
| Code | Rule | Severity | What it checks |
|---|---|---|---|
APIMATICPRE_V301 | valid-http-status-code-range | Error | A response status must be a valid HTTP status code or range. |
APIMATICPRE_V302 | valid-error-codes | Error | Only valid status codes from range 4XX (client errors) and 5XX (server errors) must be used for endpoint error definitions. |
APIMATICPRE_V303 | predefined-exception-model-for-error | Error | If an error response has a non-empty model name listed in its definition, a corresponding error model of "Exception" type must exist in the globally defined custom types. |
APIMATICPRE_V304 | unique-error-codes | Error | The errors defined for an endpoint (globally or within the endpoint) must have unique HTTP status codes. |
APIMATICPRE_V305 | valid-response-content-media-type | Error | Response content media type must be non-null and non-empty. |
APIMATICPRE_V306 | predefined-default-success-response | Error | An endpoint must consist of a default success response definition. |
APIMATICPRE_V307 | valid-predefined-default-success-response-type | Error | The default success response type of an endpoint must be non-empty, non-null and a valid primitive/complex type supported by APIMatic. |
APIMATICPRE_V308 | valid-streaming-endpoint-response-type | Error | Primitive types cannot be used as a default response type of streaming endpoints. Only model types are allowed. |
APIMATICPRE_V309 | valid-response-primitive-type | Error | Some types like "File" are not applicable to responses and, therefore, should not be used in response definitions. |
Types
| Code | Rule | Severity | What it checks |
|---|---|---|---|
APIMATICPRE_V401 | required-entity-type | Error | A valid type (primitive or a custom type) must be specified in the entity definition. |
APIMATICPRE_V402 | only-predefined-type-as-type-reference | Error | A type used in a component must either be a valid primitive type supported by APIMatic or a model/complex type for which a corresponding custom type must be defined globally. |
APIMATICPRE_V403 | native-primitive-type | Error | A component in SDL can only use primitive types which are supported by APIMatic. |
APIMATICPRE_V404 | required-default-value-for-constant-entity | Error | Entities set as constants must have a non-null and non-empty default value set. |
APIMATICPRE_V405 | supported-default-value | Error | For some types (primary or complex), default values are currently not supported and are required to be removed. |
APIMATICPRE_V406 | exception-model-only-for-error | Error | Exception types can only be referenced by error definitions. All other entities can only reference a Structure or Enumeration type model. |
APIMATICPRE_V407 | dynamic-entity-cannot-be-array | Error | If an entity has the type "Dynamic", it cannot be declared as an array. |
APIMATICPRE_V408 | 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. |
APIMATICPRE_V409 | valid-global-type-combinators-reference-name | Error | If a global type combinators reference name is specified, the name must be non-null, non-empty and an entry with that name must be present in the global type combinators definitions. |
Global Types/Models
| Code | Rule | Severity | What it checks |
|---|---|---|---|
APIMATICPRE_V501 | unique-model-name | Error | Names of globally defined custom types/models must be unique. |
APIMATICPRE_V502 | same-model-and-base-model-implementation-type | Error | The implementation type of the model and that of its base type must be the same. This means that exception models cannot have structure type models as base types nor can structure type models have exception type models as base types. |
APIMATICPRE_V503 | required-discriminator-field | Error | If a discriminator is set for a model, it must have a corresponding discriminator field/property defined in its fields. |
APIMATICPRE_V504 | valid-discriminator-field | Error | If a discriminator is set for the model, a corresponding discriminator field should be part of the model fields. This discriminator field should be optional and of "String" type only. The name of the discriminator field must match with the name of the discriminator set in the model. |
APIMATICPRE_V505 | single-declaration-of-discriminator | Error | The discriminator must be declared once and in the base type only. |
APIMATICPRE_V506 | model-circular-inheritance | Error | Models must not contain circular inheritance in their hierarchy. |
APIMATICPRE_V507 | unique-discriminator-value | Error | A base type model and its children types must all have unique discriminator values. |
APIMATICPRE_V508 | required-discriminator-value | Error | A model containing a discriminator in its type hierarchy must have a discriminator value set in its definition. |
APIMATICPRE_V509 | required-discriminator-with-discriminator-value | Error | If a discriminator value is provided in a model, a discriminator property name must also be set somewhere in the model or its type hierarchy along with the property's definition. |
APIMATICPRE_V510 | no-enum-base-type | Error | Enumeration types must not have a base type set. |
APIMATICPRE_V511 | valid-custom-type-field-primitive-type | Error | Some types like "File", "Void" and "Dynamic" are not applicable to model fields and, therefore, should not be used in field definitions. |
APIMATICPRE_V512 | atleast-one-enum-field | Error | Enumeration types must contain at least one value field. |
APIMATICPRE_V513 | unique-enum-fields | Error | All enumeration model fields must have unique default values. |
APIMATICPRE_V514 | valid-enum-field-types | Error | All fields of an enumeration model must have the same type: "String" or "Number". Other types are currently not supported. |
APIMATICPRE_V515 | enum-field-cannot-be-array | Error | An enumeration model field cannot be set as an array. |
APIMATICPRE_V516 | required-enum-default-value | Error | All fields of an enumeration model must have a non-empty and non-null default value set. The default values represent the set of possible values of the enumeration and, therefore, cannot be empty or null. |
APIMATICPRE_V517 | valid-numeric-enum-default-value | Error | The default value of a numeric enumeration model must be a valid number/integer. |
APIMATICPRE_V518 | field-read-only-and-write-only-mutual-exclusiveness | Error | A custom type field/property may be marked as read-only or write-only but not both. |
APIMATICPRE_V581 | non-empty-global-type-combinators-key | Error | The unique key/name specified for the global type combinators entry must be non-null and non-empty. |
APIMATICPRE_V582 | global-type-combinators-id-exists | Warning | 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. It is mostly useful for export to other formats that support global type combinators. |
APIMATICPRE_V583 | unique-global-type-combinators-id | Warning | 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. |
APIMATICPRE_V584 | non-empty-discriminator-mapping-key | Error | Possible discriminator values provided as keys of the discriminator mapping information must be non-null and non-empty. |
APIMATICPRE_V585 | discriminator-mapping-value-a-valid-model-name | Error | Discriminator mapping value must specify the name of the concrete type/model 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 match exactly with the name of a pre-defined custom type or model. |
APIMATICPRE_V586 | required-discriminator-with-discriminator-mapping | Warning | Discriminator mapping values indicate possible values that a discriminator property can have in a data. Therefore, the discriminator property name must be present when defining the mapping information. |
APIMATICPRE_V587 | discriminator-mapping-values-for-all-involved-models | Warning | Discriminator mapping values indicate possible values that a discriminator property can have in a data and which concrete models they map to. This helps in the deserialization process. It is, therefore, expected that a mapping value is provided for each of the models involved in the type combinator definition and a missing value for any model would indicate incomplete information. |
APIMATICPRE_V588 | all-model-types-in-type-combinator-with-discriminator | Error | A discriminator property in a global type combinator definition helps simplify deserialization of model types. This means that the types involved must be complex objects. If only primitive types are expected, a discriminator property is not applicable. |
APIMATICPRE_V589 | no-circular-reference-in-global-type-combinators-definition | Error | If a global type combinators definition references another definition (alias or not), the reference must be resolvable and not form any kind of loop. |
XML Attributes
| Code | Rule | Severity | What it checks |
|---|---|---|---|
APIMATICPRE_V601 | valid-xml-name-conventions | Error | Name assigned to an XML entity must follow W3C Extensible Markup Language recommendations. |
APIMATICPRE_V602 | required-node-name-for-xml-entity | Error | An entity marked as an XML entity must declare a non-empty and non-null XML node name. |
APIMATICPRE_V603 | only-scalar-types-for-xml-attribute | Error | A field declared as an attribute must only use scalar data types. |
APIMATICPRE_V604 | xml-attribute-cannot-be-array-or-map | Error | A field declared as an XML attribute cannot be declared as an array or map. |
APIMATICPRE_V605 | no-namespace-for-xml-attribute | Error | A namespace cannot be declared for a field set as an XML attribute. |
APIMATICPRE_V606 | no-xml-wrapping-for-non-array-entity | Error | XML wrapping cannot be used for non-array entities. |
APIMATICPRE_V607 | entity-cannot-be-xml-attribute | Error | The current entity type cannot qualify as an XML attribute and therefore can only be marked as an XML element. |
Miscellaneous
| Code | Rule | Severity | What it checks |
|---|---|---|---|
APIMATICPRE_V701 | required-entity-name | Error | A non-null, non-empty, user-friendly name or identifier must be provided for the entity. |