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.

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:

PropertyTypeDetails
SkipCodeGenerationChecksBooleanWhen 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.
SkipLintingBooleanDefault: false. When set to true, all linting rulesets will be entirely skipped and only validation rulesets will be applied.
RulesetsMap[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:

PropertyTypeDetails
SkipBooleanDefault: false. When set to true, all checks from the ruleset will be skipped/ignored. Only applicable for linting rulesets.
SeverityRule SeverityThe 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.
FilePathStringRelative path to a custom ruleset file.
RulesRules ConfigurationConfiguration 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:

PropertyTypeDetails
EnableAllBooleanDefault: 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.
EnableOnlyArray[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.
EnableArray[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.
SkipArray[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.
SeverityMap[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 NameTypeDescription
IdStringRequired. Unique identifier of the ruleset. Use only alphanumeric characters or dashes.
RulesArray[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.
NameStringA short user-friendly name of the ruleset.
DescriptionStringA detailed description of the ruleset.
SeveritySeverityDefault: Warning. Global declaration of severity of all rules. Can be overridden at rule level.
ExternalLinksArray[String]List of external links that may provide additional details about the ruleset.
TagsArray[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 NameTypeDescription
IdStringRequired. Unique identifier of the rule across the ruleset. Use only alphanumeric characters or dashes.
TargetsArray[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.
VerificationMethodVerification MethodRequired. Name of the pre-defined method that needs to be applied on the selected object as part of the rule verification.
VerificationMethodArgsMap[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.
MessageStringThe 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.
SeveritySeverityBy default, the ruleset level global severity will be applicable (Warning by default). The global severity can be overridden with the severity specified here.
NameStringShort user-friendly name for the rule.
DescriptionStringDescribes the rule in detail e.g. it can specify what kind of verification is expected and on what types of target components.
ExternalLinksArray[String]External links that can provide more details about the current rule.
HintsArray[String]Any tips/suggestions that can help someone easily resolve the violations of the current rule.
TagsArray[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 NameTypeDescription
JsonPathStringRequired. A valid JSONPath expression that helps locate and select the component(s) on which the rule needs to be applied.
KeysOnlyBooleanThe 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.
SelectWithKeysArray[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.
IgnoreWithKeysArray[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 NameDescription
PatternMore details can be found here.
OrderMore details can be found here.
LengthMore details can be found here.