Repository: stoplightio/spectral
Pull request #355 (2019-07-09 22:44:39)

docs(rulesets): rename OAS to OpenAPI
**Checklist**

- [x] Tests added / updated
- [x] Docs added / updated
- [x] Check this off Breaking change?

**Does this PR introduce a breaking change?**

- [ ] Yes
- [x] No

As requested by Marc :)

Note: we execute rules in order, therefore I had to update the tests to reflect the changes.


Patch:
diff --git a/docs/rulesets.md b/docs/rulesets.md
index 96976ff2..9ee42b43 100644
--- a/docs/rulesets.md
+++ b/docs/rulesets.md
@@ -103,7 +103,11 @@ rules:
 
 The example above will run all of the rules defined in the `spectral:oas2` ruleset (rather than the default behavior that runs just the recommended ones), with one exceptions - we turned `operation-operationId-unique` off.
 
-The current recommended rules are marked with the property `recommended: true` in their respective directories: [OAS2](https://github.com/stoplightio/spectral/tree/develop/src/rulesets/oas2), [OAS3](https://github.com/stoplightio/spectral/tree/develop/src/rulesets/oas3)
+The current recommended rules are marked with the property `recommended: true` in their respective rulesets:
+
+- [Rules relevant to OpenAPI v2 and v3](https://github.com/stoplightio/spectral/tree/develop/src/rulesets/oas/index.json)
+- [Rules specific to OpenAPI v2](https://github.com/stoplightio/spectral/tree/develop/src/rulesets/oas2/index.json)
+- [Rules specific to OpenAPI v3](https://github.com/stoplightio/spectral/tree/develop/src/rulesets/oas3/index.json)
 
 ### Changing the severity of a rule
 
diff --git a/src/rulesets/oas2/index.json b/src/rulesets/oas2/index.json
index f1eed7e8..7934e42d 100644
--- a/src/rulesets/oas2/index.json
+++ b/src/rulesets/oas2/index.json
@@ -1,6 +1,108 @@
 {
   "extends": ["spectral:oas"],
   "rules": {
+    "api-host": {
+      "description": "OpenAPI `host` must be present and non-empty string.",
+      "recommended": true,
+      "type": "style",
+      "given": "$",
+      "then": {
+        "field": "host",
+        "function": "truthy"
+      },
+      "tags": [
+        "api"
+      ]
+    },
+    "api-schemes": {
+      "description": "OpenAPI host `schemes` must be present and non-empty array.",
+      "recommended": true,
+      "type": "style",
+      "given": "$",
+      "then": {
+        "field": "schemes",
+        "function": "schema",
+        "functionOptions": {
+          "schema": {
+            "items": {
+              "type": "string"
+            },
+            "minItems": 1,
+            "type": "array"
+          }
+        }
+      },
+      "tags": [
+        "api"
+      ]
+    },
+    "host-not-example": {
+      "description": "Server URL should not point at `example.com`.",
+      "recommended": false,
+      "type": "style",
+      "given": "$",
+      "then": {
+        "field": "host",
+        "function": "pattern",
+        "functionOptions": {
+          "notMatch": "example\\.com"
+        }
+      }
+    },
+    "host-trailing-slash": {
+      "description": "Server URL should not have a trailing slash.",
+      "recommended": true,
+      "type": "style",
+      "given": "$",
+      "then": {
+        "field": "host",
+        "function": "pattern",
+        "functionOptions": {
+          "notMatch": "/$"
+        }
+      }
+    },
+    "model-description": {
+      "description": "Definition `description` must be present and non-empty string.",
+      "recommended": false,
+      "type": "style",
+      "given": "$..definitions[*]",
+      "then": {
+        "field": "description",
+        "function": "truthy"
+      }
+    },
+    "operation-security-defined": {
+      "description": "Operation `security` values must match a scheme defined in the `securityDefinitions` object.",
+      "recommended": true,
+      "type": "validation",
+      "given": "$",
+      "then": {
+        "function": "oasOpSecurityDefined",
+        "functionOptions": {
+          "schemesPath": [
+            "securityDefinitions"
+          ]
+        }
+      },
+      "tags": [
+        "operation"
+      ]
+    },
+    "valid-example": {
+      "description": "Examples must be valid against their defined schema.",
+      "message": "\"{{property}}\" property {{error}}",
+      "recommended": true,
+      "type": "validation",
+      "given": "$..[?(@.example)]",
+      "then": {
+        "function": "schemaPath",
+        "functionOptions": {
+          "field": "example",
+          "schemaPath": "$"
+        }
+      }
+    },
     "oas2-schema": {
       "description": "Validate structure of OpenAPIv2 specification.",
       "message": "{{error}}",
@@ -1637,108 +1739,6 @@
       "tags": [
         "schema"
       ]
-    },
-    "api-host": {
-      "description": "OpenAPI `host` must be present and non-empty string.",
-      "recommended": true,
-      "type": "style",
-      "given": "$",
-      "then": {
-        "field": "host",
-        "function": "truthy"
-      },
-      "tags": [
-        "api"
-      ]
-    },
-    "api-schemes": {
-      "description": "OpenAPI host `schemes` must be present and non-empty array.",
-      "recommended": true,
-      "type": "style",
-      "given": "$",
-      "then": {
-        "field": "schemes",
-        "function": "schema",
-        "functionOptions": {
-          "schema": {
-            "items": {
-              "type": "string"
-            },
-            "minItems": 1,
-            "type": "array"
-          }
-        }
-      },
-      "tags": [
-        "api"
-      ]
-    },
-    "host-not-example": {
-      "description": "Server URL should not point at `example.com`.",
-      "recommended": false,
-      "type": "style",
-      "given": "$",
-      "then": {
-        "field": "host",
-        "function": "pattern",
-        "functionOptions": {
-          "notMatch": "example\\.com"
-        }
-      }
-    },
-    "host-trailing-slash": {
-      "description": "Server URL should not have a trailing slash.",
-      "recommended": true,
-      "type": "style",
-      "given": "$",
-      "then": {
-        "field": "host",
-        "function": "pattern",
-        "functionOptions": {
-          "notMatch": "/$"
-        }
-      }
-    },
-    "model-description": {
-      "description": "Definition `description` must be present and non-empty string.",
-      "recommended": false,
-      "type": "style",
-      "given": "$..definitions[*]",
-      "then": {
-        "field": "description",
-        "function": "truthy"
-      }
-    },
-    "operation-security-defined": {
-      "description": "Operation `security` values must match a scheme defined in the `securityDefinitions` object.",
-      "recommended": true,
-      "type": "validation",
-      "given": "$",
-      "then": {
-        "function": "oasOpSecurityDefined",
-        "functionOptions": {
-          "schemesPath": [
-            "securityDefinitions"
-          ]
-        }
-      },
-      "tags": [
-        "operation"
-      ]
-    },
-    "valid-example": {
-      "description": "Examples must be valid against their defined schema.",
-      "message": "\"{{property}}\" property {{error}}",
-      "recommended": true,
-      "type": "validation",
-      "given": "$..[?(@.example)]",
-      "then": {
-        "function": "schemaPath",
-        "functionOptions": {
-          "field": "example",
-          "schemaPath": "$"
-        }
-      }
     }
   }
 }
diff --git a/src/rulesets/oas3/index.json b/src/rulesets/oas3/index.json
index 1ea5446a..be203a51 100644
--- a/src/rulesets/oas3/index.json
+++ b/src/rulesets/oas3/index.json
@@ -1,6 +1,96 @@
 {
   "extends": ["spectral:oas"],
   "rules": {
+    "api-servers": {
+      "description": "OpenAPI `servers` must be present and non-empty array.",
+      "recommended": true,
+      "type": "style",
+      "given": "$",
+      "then": {
+        "field": "servers",
+        "function": "schema",
+        "functionOptions": {
+          "schema": {
+            "items": {
+              "type": "object"
+            },
+            "minItems": 1,
+            "type": "array"
+          }
+        }
+      },
+      "tags": [
+        "api"
+      ]
+    },
+    "model-description": {
+      "description": "Model `description` must be present and non-empty string.",
+      "recommended": false,
+      "type": "style",
+      "given": "$.components.schemas[*]",
+      "then": {
+        "field": "description",
+        "function": "truthy"
+      }
+    },
+    "operation-security-defined": {
+      "description": "Operation `security` values must match a scheme defined in the `components.securitySchemes` object.",
+      "recommended": true,
+      "type": "validation",
+      "given": "$",
+      "then": {
+        "function": "oasOpSecurityDefined",
+        "functionOptions": {
+          "schemesPath": [
+            "components",
+            "securitySchemes"
+          ]
+        }
+      },
+      "tags": [
+        "operation"
+      ]
+    },
+    "server-not-example.com": {
+      "description": "Server URL should not point at `example.com`.",
+      "recommended": false,
+      "type": "style",
+      "given": "$.servers[*]",
+      "then": {
+        "field": "url",
+        "function": "pattern",
+        "functionOptions": {
+          "notMatch": "example\\.com"
+        }
+      }
+    },
+    "server-trailing-slash": {
+      "description": "Server URL should not have a trailing slash.",
+      "recommended": true,
+      "type": "style",
+      "given": "$.servers[*]",
+      "then": {
+        "field": "url",
+        "function": "pattern",
+        "functionOptions": {
+          "notMatch": "/$"
+        }
+      }
+    },
+    "valid-example": {
+      "description": "Examples must be valid against their defined schema.",
+      "message": "\"{{property}}\" property {{error}}",
+      "recommended": true,
+      "type": "validation",
+      "given": "$..[?(@.example)]",
+      "then": {
+        "function": "schemaPath",
+        "functionOptions": {
+          "field": "example",
+          "schemaPath": "$"
+        }
+      }
+    },
     "oas3-schema": {
       "description": "Validate structure of OpenAPIv3 specification.",
       "message": "{{error}}",
@@ -2313,96 +2403,6 @@
       "tags": [
         "schema"
       ]
-    },
-    "api-servers": {
-      "description": "OpenAPI `servers` must be present and non-empty array.",
-      "recommended": true,
-      "type": "style",
-      "given": "$",
-      "then": {
-        "field": "servers",
-        "function": "schema",
-        "functionOptions": {
-          "schema": {
-            "items": {
-              "type": "object"
-            },
-            "minItems": 1,
-            "type": "array"
-          }
-        }
-      },
-      "tags": [
-        "api"
-      ]
-    },
-    "model-description": {
-      "description": "Model `description` must be present and non-empty string.",
-      "recommended": false,
-      "type": "style",
-      "given": "$.components.schemas[*]",
-      "then": {
-        "field": "description",
-        "function": "truthy"
-      }
-    },
-    "operation-security-defined": {
-      "description": "Operation `security` values must match a scheme defined in the `components.securitySchemes` object.",
-      "recommended": true,
-      "type": "validation",
-      "given": "$",
-      "then": {
-        "function": "oasOpSecurityDefined",
-        "functionOptions": {
-          "schemesPath": [
-            "components",
-            "securitySchemes"
-          ]
-        }
-      },
-      "tags": [
-        "operation"
-      ]
-    },
-    "server-not-example.com": {
-      "description": "Server URL should not point at `example.com`.",
-      "recommended": false,
-      "type": "style",
-      "given": "$.servers[*]",
-      "then": {
-        "field": "url",
-        "function": "pattern",
-        "functionOptions": {
-          "notMatch": "example\\.com"
-        }
-      }
-    },
-    "server-trailing-slash": {
-      "description": "Server URL should not have a trailing slash.",
-      "recommended": true,
-      "type": "style",
-      "given": "$.servers[*]",
-      "then": {
-        "field": "url",
-        "function": "pattern",
-        "functionOptions": {
-          "notMatch": "/$"
-        }
-      }
-    },
-    "valid-example": {
-      "description": "Examples must be valid against their defined schema.",
-      "message": "\"{{property}}\" property {{error}}",
-      "recommended": true,
-      "type": "validation",
-      "given": "$..[?(@.example)]",
-      "then": {
-        "function": "schemaPath",
-        "functionOptions": {
-          "field": "example",
-          "schemaPath": "$"
-        }
-      }
     }
   }
 }


Test patch:
diff --git a/src/__tests__/linter.test.ts b/src/__tests__/linter.test.ts
index 850d1631..7c8647ec 100644
--- a/src/__tests__/linter.test.ts
+++ b/src/__tests__/linter.test.ts
@@ -274,11 +274,6 @@ responses:: !!foo
       expect.objectContaining({
         code: 'invalid-ref',
       }),
-      expect.objectContaining({
-        code: 'oas3-schema',
-        message: "/paths//pets/get/responses/200 should have required property '$ref'",
-        path: ['paths', '~1pets', 'get', 'responses', '200'],
-      }),
       expect.objectContaining({
         code: 'model-description',
       }),
@@ -287,6 +282,11 @@ responses:: !!foo
         message: '"foo" property type should be number',
         path: ['components', 'schemas', 'foo'],
       }),
+      expect.objectContaining({
+        code: 'oas3-schema',
+        message: "/paths//pets/get/responses/200 should have required property '$ref'",
+        path: ['paths', '~1pets', 'get', 'responses', '200'],
+      }),
     ]);
   });
 
diff --git a/src/cli/commands/__tests__/lint.test.ts b/src/cli/commands/__tests__/lint.test.ts
index de9b776c..0e1f2d33 100644
--- a/src/cli/commands/__tests__/lint.test.ts
+++ b/src/cli/commands/__tests__/lint.test.ts
@@ -354,6 +354,13 @@ describe('lint', () => {
             },
             source: expect.stringContaining('src/cli/commands/__tests__/__fixtures__/refs/info.json'),
           }),
+          expect.objectContaining({
+            code: 'api-schemes',
+            message: 'OpenAPI host `schemes` must be present and non-empty array.',
+            path: ['schemes'],
+            range: expect.any(Object),
+            source: expect.stringContaining('src/cli/commands/__tests__/__fixtures__/draft-ref.oas2.json'),
+          }),
           expect.objectContaining({
             code: 'oas2-schema',
             message: '/info Property foo is not expected to be here',
@@ -370,13 +377,6 @@ describe('lint', () => {
             },
             source: expect.stringContaining('src/cli/commands/__tests__/__fixtures__/refs/info.json'),
           }),
-          expect.objectContaining({
-            code: 'api-schemes',
-            message: 'OpenAPI host `schemes` must be present and non-empty array.',
-            path: ['schemes'],
-            range: expect.any(Object),
-            source: expect.stringContaining('src/cli/commands/__tests__/__fixtures__/draft-ref.oas2.json'),
-          }),
         ]);
       });
 
@@ -401,6 +401,13 @@ describe('lint', () => {
             },
             source: expect.stringContaining('src/cli/commands/__tests__/__fixtures__/refs/contact.json'),
           }),
+          expect.objectContaining({
+            code: 'api-schemes',
+            message: 'OpenAPI host `schemes` must be present and non-empty array.',
+            path: ['schemes'],
+            range: expect.any(Object),
+            source: expect.stringContaining('src/cli/commands/__tests__/__fixtures__/draft-nested-ref.oas2.json'),
+          }),
           expect.objectContaining({
             code: 'oas2-schema',
             message: "/info should have required property 'title'",
@@ -417,13 +424,6 @@ describe('lint', () => {
             },
             source: expect.stringContaining('src/cli/commands/__tests__/__fixtures__/refs/contact.json'),
           }),
-          expect.objectContaining({
-            code: 'api-schemes',
-            message: 'OpenAPI host `schemes` must be present and non-empty array.',
-            path: ['schemes'],
-            range: expect.any(Object),
-            source: expect.stringContaining('src/cli/commands/__tests__/__fixtures__/draft-nested-ref.oas2.json'),
-          }),
         ]);
       });
   });