Overview
When a user uploads an API specification document on APIMatic, the document is passed through certain validation steps during which a number of validation messages may be shown to the user as output. The severity of the messages will indicate whether the user can proceed to do other actions on our products with his document or not e.g. transforming the API to some other format, generating an SDK or a portal, etc.
Key Concepts
Rules and Rulesets
Each message shown to the user indicates a rule that was violated. Related rules are grouped together in documents called rulesets. Therefore, a rule is uniquely identified by knowing the id of the ruleset to which the rule belongs (e.g. apimatic-preliminary-validation) and the id of the rule itself (e.g. required-server-url ). If you prefer to keep things short, the same rule can also be uniquely identified with a rule code instead e.g. APIMATICPRE_V036.
Severity of Messages
The severity of the messages can range from Blocking (very severe) to Information (not severe):
| Severity Level | Details |
|---|---|
| Blocking | This is more severe than an Error. It indicates that the validation process has found a critical issue in the document that needs to be resolved before the document can be further validated. |
| Error | This is less severe than a Blocking error but is more severe than a Warning. It indicates presence of one or more syntax or semantic issues in the API specification document e.g. a request body defined in a GET method. An error will not block the validation process. However, the document needs to be fixed before it can be used to generate any further output e.g. transformed output, SDK, portal, etc. |
| Warning | This is less severe than an Error but more severe than an Information message. It indicates presence of one or more syntax/semantic issues in the API specification document which are not always severe enough to block the output generation. However, not fixing these issues in the document can affect the quality of the output e.g. a message indicating that the name exceeds maximum length restrictions can have adverse effects on the generated output. |
| Information | This is the least severe form of a message. These are generally just recommendations or suggestions that can help enhance your API definition and its completeness e.g. messages that point out that an endpoint description or a parameter example is missing. |
Rule System of a Message
The messages shown to the users can belong to two types of rule systems:
| Rule System | Details |
|---|---|
| Syntax | This system of rules is related to validity of structure of statements or expressions. It dictates which combinations of symbols, statements or expressions is valid and which is not e.g. JSON syntax dictates that all property keys are enclosed in quotes. |
| Semantic | As opposed to the syntax rule system, semantic rule system is more related to whether the constructs convey the correct meaning or are contexually valid or not e.g. a request body should not be defined in a GET method. This is syntactically valid but does not follow the semantic rule system. |
Validation versus Linting Rules
| Rule Type | Details |
|---|---|
| Validation | Validation rules check for whether your API description is valid against pre-defined standards of the format in which your API description is written. Additionally, there can be checks to ensure that your API description is technically correct or not e.g. a parameter must have a name is a validation rule. |
| Linting | Linting rules are mostly style checks that are not part of the format standards but can otherwise help enhance you API description. e.g. a parameter must have a description is a linting rule. |
Validation Rulesets
Links to reference documentation for each ruleset containing further details can be found below.
APIMatic Validation Rulesets
List of validation rulesets containing rules against which APIMatic validates an API specification document are given below: