Skip to main content

Added Support For Swagger v2.0 and OpenAPI v3.0 Validation and Linting

· 9 min read

As part of our efforts to improve existing format-specific validation, we are now introducing validators for Swagger v2.0 and OpenAPI v3.0 specifications.

Previous Status of Validation

Previously, we were only utilizing flexible format-specific validation approach, which did not encompass all standard checks. Our primary focus was to make the best possible attempt to import or transform a specification even in the presence of issues, except for those that completely blocked the process.

Furthermore, the validation messages that we provided offered minimal metadata pertaining to the actual issues, making it occasionally arduous to resolve the problems within the specification.

We also lacked the capability to configure the linting checks within our validation system.

Introducing Stricter Validation and Enhanced Linting

We are now announcing the support for format-specific stricter validation and enhanced linting in APIMatic, where your specifications get scrutinized by our new validators according to the standards defined by the respective format. This provides you with a detailed summary of the issues, including all the metadata needed to resolve an issue, such as the message itself that lets you know about the violation, the line number where the issue exactly occurred in the spec, the hints that help you think about possible ways to fix the issue and many more.

Using the Newer Validation

To enable the new stricter form of validation, we have introduced a new import setting called UseStrictValidation. This setting can be enabled by importing a metadata file along with the specification, with the UseStrictValidation import setting enabled.

Here's an example metadata file with the UseStrictValidation setting enabled:

"ImportSettings": {
"UseStrictValidation": true

OpenAPI v3.0 Standards

The OpenAPI v3.0 standards define a set of rules that must be adhered to by an OpenAPI specification, using reserved keywords such as MUST, MUST NOT, REQUIRED, SHALL, and SHALL NOT. These reserved keywords are employed to define certain rules that are mandatory for an OpenAPI spec to be valid, and these rules are referred to as standard validation rules.

Our new validation uses the concept of rulesets, where each ruleset is a group of rules with similar characteristics. The OpenAPI 3.0 standard validation rules have been segregated into 2 validation rulesets:

  1. OpenAPI v3.0 Syntax Validation
  2. OpenAPI v3.0 Standard validation

In addition to the mandatory rules, there are some rules that are considered good to have for an OpenAPI spec. These rules, referred to as standard linting rules, are defined using the reserved keywords such as SHOULD, SHOULD NOT, RECOMMENDED, and NOT RECOMMENDED.

The standard linting rules have been segregated into two linting rulesets:

  1. OpenAPI v3.0 Syntax Linting
  2. OpenAPI v3.0 Standard Linting

Our new format-specific validation incorporates all the standard validation and linting rules defined in the official OpenAPI standard documentation.

Validation Example

OpenAPI v3.0 Snippet
"/api/path": {
"get": {
"summary": "Sample API with a path",
"description": "A sample API with a path URL that contains no templates.",
"operationId": "SampleAPI",
"parameters": [
"name": "pathParam",
"in": "path",
"description": "The path parameter.",

In the above example, we have an unused path parameter since there is no template expression in the path URL. According to the OpenAPI v3.0 standard document,

If in is "path", the name field MUST correspond to a template expression occurring within the path field in the Paths Object.

So, the newer validation will log this as a violation:

Unused path parameter validation

Furthermore, when you click on the provided link within the validation message, it will direct you to a page that provides comprehensive details regarding the specific violated rule. This allows for easy access to in-depth information related to the rule that was flagged during the validation process. Follow this link for more details.


We are working towards format-specific strict validation for OpenAPI v3.1 standards as well and will be announcing their support in the near future.

Linting OpenAPI v3 Beyond Standards for Better API Consumption

While the OpenAPI v3.0 standard document tells you exactly what you need to do to ensure your OpenAPI v3.0 specification is compliant with the standards, if you need to increase your API consumption using the auto-generated SDKs and the developer experience portal, linting plays an important role. It guarantees that the generated SDK and Developer Portal offer all the necessary components to facilitate seamless API consumption.

In order to facilitate linting of the OpenAPI specification for Code and Docs Generation purposes, we have established our own set of rules. These rules ensure that the API specification provided for Code Generation meets the requirements for generating high-quality SDKs as well as producing comprehensive documentation. By adhering to these rules, we ensure that the generated SDKs and documentation are of the highest standard and effectively support developers in utilizing the API.

Here are a few examples of these rules in action:

  1. Very long titles, names, and summaries, which exceed 50 characters, can disrupt the user-friendliness of the generated Developer Portal. Subsequently, this can also lead to issues in the code generation process for SDKs. The following example illustrates this scenario:
"info": {
"title": "This is a very long info title which exceeds the limit of 50 characters.",

Title too long validation rule

  1. Another scenario is of missing examples for parameters, media types, or schemas. In addition to demonstrating the intended payload that an object is expected to accept, we use these examples for automatic generation of test cases for the API. So, it is essential for example(s) to be defined using the example or examples property.

"parameters": [
"name": "language",
"in": "query",
"required": false,
"type": "string"

Set examples ruleset

Code Generation Rulesets

Docs Generation Rulesets

For more detailed information on following best practices when creating your OpenAPI v3.0 specifications to improve API consumption, we invite you to read our blog post 14 Best Practices to Write OpenAPI for Better API Consumption.

Swagger v2.0 Standards

Despite the introduction of OpenAPI v3.0 and more recently, OpenAPI v3.1, there is still a need to cover all the validation checks for older versions as well. Swagger v2.0 is a format that is still used by many worldwide. So, we have added support for Swagger v2.0 standard rules as part of our format-specific stricter validation.

These cover all the mandatory validation checks from the Swagger v2.0 standard document, marked with keywords such as:


The Swagger v2.0 standard validation rulesets are available here.

Validating APIMatic Metadata files

Apart from OpenAPI v3.0, Swagger v2.0 validation, and linting, we have also introduced APIMatic Metadata file validation. Writing metadata files is now easier than ever for our users. Common syntax and semantic issues are now a thing of the past as the new metadata file validation aims to highlight such errors in the metadata file uploaded along with the API specification file. Further information about APIMatic Metadata files can be found here.

Metadata File Validation Ruleset

Please find the validation rulesets for metadata file here.

Support for Custom Rules Beyond Built-in Rulesets

Beyond APIMatic built-in rulesets, users can also define their own customized rulesets. Their specs would then be validated against the built-in rulesets plus the rulesets defined by them.

Custom rulesets can be defined in a file and referenced in the metadata file. Please refer to the official documentation on how to define your own custom rulesets.

In order to avoid any mistakes in defining custom rulesets, a few rules are in place to ensure that the custom rulesets have all the relevant information needed. Some of these rules are described below:

  • Required Custom Rule Id: This rule helps ensure that the rules specified in the custom ruleset have rule "id" defined that is used as a unique identifier for the rule.
  • Unique Custom Rule Id: To uniquely identify each rule. This rule is in place to prevent any rules from being introduced with a duplicate "id" property.
  • Required Custom Rule Targets: The property ‘targets’ must be specified when defining a custom rule. This helps identify the target component(s) that need to be validated.

Custom Rulesets Validation Ruleset

Please refer to this document to learn more about the validation rulesets that are set in place for defining custom rulesets.

To link a custom ruleset file through the metadata file, see the following example:

Custom Ruleset File
"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."
Metadata File
"ValidationConfiguration": {
"Rulesets": {
"my-custom-ruleset": {
"FilePath": "/path/to/ruleset/file"

Ability to Configure Validation

Both validation and linting are configurable, however, there are a greater number of configurable options for linting than there are for validation.

For instance, in the case of validation configurations, we can enable either a specific set of rules that are disabled by default or all of them. Whereas in the case of linting, we have the options to enable only a set of rules, skip a set of rules, configure the severity of rules, and skip rulesets altogether.

The following example shows how to configure linting using configuration:

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

For further details on configuring linting and validation, visit the relevant documentation.

Visit or contact us for more information.