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 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.

Swagger v2.0 Validation Rulesets

List of validation rulesets containing rules defined by the standard are given below:

OpenAPI v3.0 Validation Rulesets

List of currently available validation rulesets containing rules defined by the standard as well as additional checks required by APIMatic are given below:

APIMatic Validation Rulesets

List of validation rulesets containing rules against which APIMatic validates an API specification document are given below:

Configuring Validation

You can configure the validation process as per your requirements by providing a validation configuration in the APIMatic's Metadata file which needs to be uploaded along with the API definition/specification:

{
    "ValidationConfiguration": {
        "SkipLinting": true
    }
}

The capabilities that this configuration provides is as follows:

Skipping some rules of a ruleset, the entire ruleset or a group of rulesets e.g. skipping all linting rulesets.
Enabling only some rules from a ruleset and skipping the rest.
Enabling rules of a ruleset that are kept disabled by default either because of low priority or any other reason.
Overriding severity of rules depending on needs e.g. converting a warning into error.
note
The capabilities differ w.r.t. whether the ruleset is meant for validation or linting. Validation rules/rulesets can only be enabled but not skipped nor can their severity be changed.

Validation Configuration Object

The available properties and their respective types are as follows:

Property	Type	Details
SkipCodeGenerationChecks	Boolean	When set to `true`, linting checks associated with code/SDK generation will not be performed. Code generation checks are enabled by default unless you are performing only transformations in the API Transformer.
SkipLinting	Boolean	Default: `false`. When set to `true`, all linting rulesets will be entirely skipped and only validation rulesets will be applied.
Rulesets	Map[String, Ruleset Configuration]	Configuration for each ruleset. The key is the unique id/code that identifies a ruleset and the value provides required configurations for that ruleset. The rulesets not specified here will work with default behavior.

Example 1 - Skip all linting rules:

{
    "SkipLinting": true
}

Example 2 - Configuring a ruleset:

The following configuration will let you skip the rule no-ambiguous-path from the openapi-v3-standards-linting ruleset and also downgrade the severity of all rules in the ruleset from Warning to Information. Here, no-ambiguous-path and openapi-v3-standards-linting are rule and ruleset ids respectively.

{
    "Rulesets": {
        "openapi-v3-standards-linting": {
            "Severity": "Information",
            "Rules": {
                "Skip": ["no-ambiguous-path"]
            }
        }
    }
}

Ruleset Configuration Object

This configuration object will let you configure a single ruleset. The available properties and their respective types are as follows:

Property	Type	Details
Skip	Boolean	Default: `false`. When set to `true`, all checks from the ruleset will be skipped/ignored. Only applicable for linting rulesets.
Severity	Rule Severity	The severity set here will override severity level of all rules in the ruleset. Only applicable for linting rulesets. If a rule in this ruleset has severity overrides provided in the rules configuration of the ruleset, the rule level severity configuration will take precedence.
FilePath	String	Relative path to a custom ruleset file.
Rules	Rules Configuration	Configuration for specific rules of the ruleset can be provided here. Rules not configured explicitly or implicitly here will work with default behavior.

Example

{
    "Skip": true
}

Ruleset Rules Configuration Object

This configuration will let you configure rules of a ruleset. The available properties and their respective types are as follows:

Property	Type	Details
EnableAll	Boolean	Default: `false`. When set to `true`, all rules of the ruleset will be applied including those that may be disabled by default and any configurations provided under `EnableOnly` or `Enable` will be ignored.
EnableOnly	Array[String]	If a list of rule ids/codes is provided, only those rules from the ruleset will be applied and others will be skipped regardless of any default configuration or configurations provided using the `Enable` setting. Only applicable for linting rulesets.
Enable	Array[String]	A list of rule ids/codes to enable. This can be used to enable rules from a ruleset that may be disabled by default for any reason (low priority or any other). The default behavior will be used for rules not specified here.
Skip	Array[String]	If a list of rule ids/codes is provided, they will not be applied. Only applicable for linting rulesets. Rules listed here will be ignored regardless of any configurations provided under `EnableAll`, `EnableOnly` or `Enable`.
Severity	Map[String, Rule Severity]	This will let you override severity of a rule e.g. changing an error to warning. Only applicable for linting rulesets. The key should be the id/code of the rule you wish to change severity of.

Example 1 - Enable only selected rules from a ruleset:

{
    "EnableOnly": [
        "unique-case-insensitive-header-parameter-names", //using rule id
        "OPENAPI3STANDARDS_L065" //using rule code
    ]
}

Example 2 - Skip a rule from a ruleset:

{
    "Skip": [
        "no-ambiguous-path"
    ]
}

Example 3 - Changing severity of a rule:

{
    "Severity": [
        {
            "valid-schema-example": "Error"
        }
    ]
}

Adding Your Own Rules

note

This feature is currently only supported for OpenAPI v3.0 files and when the UseStrictValidation import setting is set to true.

If you are looking to add your own rules beyond the capabilities provided by our built-in rulesets, you can create a custom ruleset and apply that on your API specification document.

How Do Custom Rules Work?

In a custom ruleset, you can configure rules that use built-in methods to verify one or more of the selected target components. If the target component fails verification, a lint warning will be logged. The severity of these messages as well as other details can be easily configured to suit your needs when defining the rules.

Creating and Applying a Custom Ruleset File

Custom rules need to be defined inside a custom ruleset file placed at a path relative to the main API specification document. The file must use valid JSON/YAML syntax and contain the Ruleset Object at root level.

Example:

{
    "Id": "my-custom-ruleset",
    "Rules": [
        {
            "Id": "max-operation-id-length-30",
            "VerificationMethod": "Length",
            "Targets": [
                {
                    "JsonPath": "$.paths.*.*.operationId"
                }
            ],
            "VerificationMethodArgs": {
                "Maximum": 30
            },
            "Message": "Operation id is too long."
        }
    ]
}

In order to apply a custom ruleset on your API specification document, it needs to be referenced from within a APIMatic Metadata file's validation configuration as shown below:

{
    "ValidationConfiguration": {
        "Rulesets": {
            "my-custom-ruleset": {
                "FilePath": "/path/to/ruleset/file"
            }
        }
    }
}

Ruleset Object

This object represents the root object that is placed in a custom ruleset file. The available properties are listed below:

Property Name	Type	Description
Id	String	Required. Unique identifier of the ruleset. Use only alphanumeric characters or dashes.
Rules	Array[Custom Lint Rule Object]	Required. List of custom rule definitions that need to be applied on target components. The list must contain at least one rule definition.
Name	String	A short user-friendly name of the ruleset.
Description	String	A detailed description of the ruleset.
Severity	Severity	Default: `Warning`. Global declaration of severity of all rules. Can be overridden at rule level.
ExternalLinks	Array[String]	List of external links that may provide additional details about the ruleset.
Tags	Array[String]	Tags that will be shown along with rules of the ruleset for more context and to facilitate searching.

Custom Lint Rule Object

The available properties to describe a custom rule are listed below:

Property Name	Type	Description
Id	String	Required. Unique identifier of the rule across the ruleset. Use only alphanumeric characters or dashes.
Targets	Array[Rule Target Object]	Required. Identifies the target components that need to be verified with the current rule. The list must contain at least one target.
VerificationMethod	Verification Method	Required. Name of the pre-defined method that needs to be applied on the selected object as part of the rule verification.
VerificationMethodArgs	Map[String, Any]	Key-value pairs containing arguments to pass to the verification method where the key represents the argument name. Depending upon the selected `VerificationMethod`, one or more arguments may be required.
Message	String	The message that needs to be displayed during the validation process if a violation of the rule is found. If not specified, a default message will be used. It is recommended to keep this message short.
Severity	Severity	By default, the ruleset level global severity will be applicable (`Warning` by default). The global severity can be overridden with the severity specified here.
Name	String	Short user-friendly name for the rule.
Description	String	Describes the rule in detail e.g. it can specify what kind of verification is expected and on what types of target components.
ExternalLinks	Array[String]	External links that can provide more details about the current rule.
Hints	Array[String]	Any tips/suggestions that can help someone easily resolve the violations of the current rule.
Tags	Array[String]	Tags that can be shown with the rule for more context and to help in searching as well.

Rule Target Object

The available properties to help select rule target component(s) are listed below:

Property Name	Type	Description
JsonPath	String	Required. A valid JSONPath expression that helps locate and select the component(s) on which the rule needs to be applied.
KeysOnly	Boolean	The target objects will be converted into a list of keys (extracted from the top level of an object). Only applicable if selected target(s) are objects.
SelectWithKeys	Array[String]	For each target object, only properties with specified keys will be evaluated. Mutually exclusive with `IgnoreWithKeys`. Only applicable if selected target(s) are objects.
IgnoreWithKeys	Array[String]	For each target object, properties with specified keys will not be evaluated. Mutually exclusive with `SelectWithKeys`. Only applicable if selected target(s) are objects.

Verification Methods

Available verification methods are listed below:

Method Name	Description
Pattern	More details can be found here.
Order	More details can be found here.
Length	More details can be found here.

Key Concepts​

Rules and Rulesets​

Severity of Messages​

Rule System of a Message​

Validation versus Linting Rules​

Validation Rulesets​

Swagger v2.0 Validation Rulesets​

OpenAPI v3.0 Validation Rulesets​

APIMatic Validation Rulesets​

Configuring Validation​

Validation Configuration Object​

Ruleset Configuration Object​

Ruleset Rules Configuration Object​

Adding Your Own Rules​

How Do Custom Rules Work?​

Creating and Applying a Custom Ruleset File​

Ruleset Object​

Custom Lint Rule Object​

Rule Target Object​

Verification Methods​