Skip to main content

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 LevelDetails
BlockingThis 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.
ErrorThis 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.
WarningThis 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.
InformationThis 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 SystemDetails
SyntaxThis 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.
SemanticAs 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 TypeDetails
ValidationValidation 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.
LintingLinting rules are generally style checks or recommendations that can help enhance you API description document. However, not complying with those checks will not make your document invalid. 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: