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:
- OpenAPI v3 Syntax Validation
- OpenAPI v3 Standards Validation
- OpenAPI v3 Syntax Linting
- OpenAPI v3 Standards Linting
- OpenAPI v3 APIMatic Linting
- OpenAPI v3 APIMatic Syntax Linting
- OpenAPI v3 Linting for APIMatic Code Generation
- OpenAPI v3 Syntax Linting for APIMatic Code Generation
- OpenAPI v3 Linting for APIMatic Portal Generation
- OpenAPI v3 Syntax Linting for APIMatic Portal Generation
APIMatic Validation Rulesets
List of validation rulesets containing rules against which APIMatic validates an API specification document are given below:
- APIMatic Post-Processing Validation
- APIMatic Post-Processing Validation for Code-Generation
- APIMatic Preliminary Validation
- APIMatic Preliminary Linting
- APIMatic Validation for Code Generation
- APIMatic Linting for Portal Generation
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.
noteThe 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
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. |