Adding Your Own Rules

note

This feature is currently only supported for OpenAPI v2.0 and v3.0 files and works only 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.