docs: SVG for the readme and a quick go at cli

README.md

@@ -5,115 +5,97 @@
 [![Build Status](https://dev.azure.com/vncz/vncz/_apis/build/status/stoplightio.spectral?branchName=develop)](https://dev.azure.com/vncz/vncz/_build/latest?definitionId=4&branchName=develop)
 [![CircleCI](https://circleci.com/gh/stoplightio/spectral.svg?style=svg)](https://circleci.com/gh/stoplightio/spectral)
 
-A flexible JSON object linter with out of the box support for OpenAPI v2 and v3
+A flexible JSON linter with out of the box support for OpenAPI v2 and v3.
+
+![Demo of Spectral linting an OpenAPI document from the CLI](./docs/demo.svg)
 
 ## Features
 
-- Create custom rules to lint _any JSON object_
-- Use JSON paths to apply rules / functions to specific parts of your JSON objects
-- Built-in set of functions to help [build custom rules](#creating-a-custom-rule). Functions include pattern checks, parameter checks, alphabetical ordering, a specified number of characters, provided keys are present in an object, etc
-- [Create custom functions](#creating-a-custom-function) for advanced use cases
-- Optional ready to use rules and functions to validate and lint [OpenAPI v2 _and_ v3 documents](#example-linting-an-openapi-document)
-- Validate JSON with [Ajv](https://github.com/epoberezkin/ajv)
+- Create custom rules to lint JSON or YAML objects
+- Ready to use rules to validate and lint OpenAPI v2 _and_ v3 documents
+- Use JSON path to apply rules to specific parts of your objects
+- Built-in set of functions to help [create custom rules](./docs/rulesets.md). Functions include pattern checks, parameter checks, alphabetical ordering, a specified number of characters, provided keys are present in an object, etc.
+- Create custom functions for advanced use cases
+- Validate JSON with [Ajv](https://www.npmjs.com/package/ajv)
 
 ## Installation
 
-### Local Installation
-
-```bash
-npm install @stoplight/spectral
-```
-
-### Global Installation
+Spectral's CLI can be installed via npm or yarn.
 
 ```bash
 npm install -g @stoplight/spectral
-```
 
-Supports Node v8.3+ and modern browsers.
-
-### Executable binaries
+# OR
 
-For users without Node and/or NPM/Yarn, we provide standalone packages for all major platforms. We also provide a shell script to auto download the executable based on your operating system:
-
-`curl -L https://raw.githack.com/stoplightio/spectral/master/install.sh | sh`
-
-Note, the binaries are *not* auto-updatable, therefore you will need to download a new version on your own.
-
-#### Installing binaries system-wide
+yarn global add @stoplight/spectral
+```
 
-##### Linux
+Spectral is avaiable as a Docker image as well
 
 ```bash
-sudo mv ./spectral-linux /usr/local/bin/spectral
+docker run --rm -it stoplight/spectral lint "${url}"`
 ```
 
-You may need to restart your terminal.
-Now, `spectral` command will be accessible in your terminal.
-
-Head over to [releases](https://github.com/stoplightio/spectral/releases) for the latest binaries.
-
+If the file you want to lint is on your computer, you'll need to mount the directory where the file resides as a volume
 
-### Docker
 ```bash
-docker run --rm -it stoplight/spectral lint "${URL}"
+docker run --rm -it -v $(pwd):/tmp stoplight/spectral lint "/tmp/file.yaml"
 ```
 
+Finally, [executable binaries](#executable-binaries) are also available.
+
 ## Usage
 
 ### CLI
 
-Spectral can be run via the command-line:
+After installing via one of the methods above, Spectral can be used via your command-line. Take a look at the [CLI docs](./docs/cli.md) for information on the options available.
 
-```bash
-spectral lint petstore.yaml
-```
+### Examples
 
-Other options include:
-
-``` text
-  -e, --encoding=encoding      text encoding to use
-  -f, --format=json|stylish    formatter to use for outputting results
-  -h, --help                   show CLI help
-  -o, --output=output          output to a file instead of stdout
-  -q, --quiet                  no logging - output only
-  -r, --ruleset=ruleset        path to a ruleset file (supports remote files)
-  -s, --skip-rule=skip-rule    ignore certain rules if they are causing trouble
-  -v, --verbose                increase verbosity
-```
-
-> Note: The Spectral CLI supports both YAML and JSON.
-
-Currently, Spectral CLI supports validation of OpenAPI documents and lints them based on our default ruleset, or you can provide [your own rulesets](docs/rulesets.md).
+- [Adding a rule](./docs/rulesets.md#adding-a-rule)
+- [Adding to the recommended OpenAPI rules](./docs/rulesets.md#adding-to-the-recommended-openapi-rules)
+- [Enabling specific OpenAPI rules](./docs/rulesets.md#enabling-specific-openapi-rules)
+- [Disabling specific OpenAPI rules](./docs/rulesets.md#disabling-specific-openapi-rules)
+- [Changing the severity of a rule](./docs/rulesets.md#changing-the-severity-of-a-rule)
 
 ## Concepts
 
-There are three key concepts in Spectral: **Rulesets**, **Rules** and **Functions**.
+There are three key concepts in Spectral: **Rulesets**, **Rules**, and **Functions**.
 
-- **Ruleset** is a container for a collection of rules and functions.
-- **Rule** filters your object down to a set of target values, and specify the function that should evaluate those values.
-- **Function** accept a value and return issue(s) if the value is incorrect.
+- **Rulesets** act as a container for rules and functions.
+- **Rules** filter your object down to a set of target values, and specify the function that is used to evaluate those values.
+- **Functions** accept a value and return issue(s) if the value is incorrect.
 
-Think of a set of **rules** and **functions** as a flexible and customizable style guide for your JSON objects.
+Think of a **Spectral ruleset** as a flexible and customizable style guide for your JSON objects.
 
 ## Programmatic usage
 
-Spectral is written in TypeScript (JavaScript) and can be used directly for when you need to use Spectral programmatically. Take a look at our ["JavaScript API documentation"](docs/js-api.md).
+Spectral is written in TypeScript (then compiled to JavaScript) and can be used directly for when you need to use Spectral programmatically. Take a look at our ["JavaScript API documentation"](docs/js-api.md).
 
 ## FAQs
 
-**How is this different than [Ajv](https://github.com/epoberezkin/ajv)?**
+#### How is this different than [Ajv](https://www.npmjs.com/package/ajv)?
 
 Ajv is a JSON Schema validator, not a linter. Spectral does expose a `schema` function that you can use in your rules to validate all or part of the target object with JSON Schema (Ajv is used under the hood). However, Spectral also provides a number of other functions and utilities that you can use to build up a linting ruleset to validates things that JSON Schema is not well suited for.
 
-**I want to lint my OpenAPI documents but don't want to implement Spectral right now.**
+#### I want to lint my OpenAPI documents but don't want to implement Spectral right now.
 
 No problem! A hosted version of Spectral comes **free** with the Stoplight platform. Sign up for a free account [here](https://stoplight.io/?utm_source=github&utm_campaign=spectral).
 
-**What is the difference between Spectral and [Speccy](https://github.com/wework/speccy)?**
+#### What is the difference between Spectral and [Speccy](https://github.com/wework/speccy)?
 
 With Spectral, lint rules can be applied to _any_ JSON object. Speccy is designed to work with OpenAPI v3 only. The rule structure is different between the two. Spectral uses [JSONPath](http://goessner.net/articles/JsonPath/) `path` parameters instead of the `object` parameters (which are OpenAPI specific). Rules are also more clearly defined (thanks to TypeScript typings) and now require specifying a `type` parameter. Some rule types have been enhanced to be a little more flexible along with being able to create your own rules based on the built-in and custom functions.
 
+### Executable binaries
+
+For users without Node and/or NPM/Yarn, we provide standalone packages for [all major platforms](https://github.com/stoplightio/spectral/releases). We also provide a shell script to auto download the executable based on your operating system:
+
+```bash
+curl -L https://raw.githack.com/stoplightio/spectral/master/install.sh | sh
+```
+
+Note, the binaries are *not* auto-updatable, therefore you will need to download a new version on your own.
+
 ## Contributing
 
 If you are interested in contributing to Spectral itself, check out our [contributing docs](CONTRIBUTING.md) to get started.

docs/cli.md

@@ -0,0 +1,25 @@
+# Spectral CLI
+
+Once installed, Spectral can be run via the command-line:
+
+```bash
+spectral lint petstore.yaml
+```
+
+Other options include:
+
+``` text
+  -e, --encoding=encoding      text encoding to use
+  -f, --format=json|stylish    formatter to use for outputting results
+  -h, --help                   show CLI help
+  -o, --output=output          output to a file instead of stdout
+  -q, --quiet                  no logging - output only
+  -r, --ruleset=ruleset        path to a ruleset file (supports remote files)
+  -s, --skip-rule=skip-rule    ignore certain rules if they are causing trouble
+  -v, --verbose                increase verbosity
+  --max-results=max-results    [default: all] maximum results to show
+```
+
+> Note: The Spectral CLI supports both YAML and JSON.
+
+Currently, Spectral CLI supports validation of OpenAPI documents and lints them based on our default ruleset, or you can create and use [your own rulesets](./rulesets.md).

docs/rulesets.md

@@ -1,41 +1,129 @@
----
-title: Spectral Rulesets
-tags: 
-- Documentation
-- Rulesets
----
+# Spectral Rulesets
 
-Rulesets are a container for collections of rules. These rules are essentially calling functions Spectral, and by taking parameters you can make these functions do whatever you want. 
+Rulesets are a container for collections of rules. These rules are taking parameters, and calling functions on certain parts of the JSON object being linted.
 
-First the rule filters your object (JSON/YAML file) down to a set of target values, and then list what function arguments should be passed in.
+## CLI Usage
 
-## Usage
+To get a general overview of the CLI usage, please refer to the dedicated [documentation page](./cli.md)
 
-```bash
-spectral lint foo.yaml --ruleset=path/to/acme-company-ruleset.yaml --ruleset=http://example.com/acme-common-ruleset.yaml
+When you run the `spectral lint my-document.json` CLI command, Spectral will automatically apply the built in OpenAPI v2 or v3 ruleset if appropriate.
+
+To customize the rules that are applied, create a `spectral.yml` in the same directory that you are running the `spectral lint` command from and it will automatically be used.
+
+## Ruleset Examples
+
+Spectral currently support ruleset files in both `yaml` and `json` formats.
+
+### Adding a rule
+
+Add your own rules under the `rules` property in your `spectral.yml` ruleset file.
+
+**spectral.yml**
+
+```yaml
+rules:
+  my-rule-name:
+    description: Tags must have a description.
+    given: $.tags[*]
+    severity: error
+    then:
+      field: description
+      function: truthy
 ```
 
-## Example Ruleset
+The example above adds a single rule that checks that tags objects have a description property defined.
+
+Running `spectral lint` on the following object with the ruleset above will result in an error being reported, since the tag does not have a description:
+
+```json
+{
+  "tags": [{
+    "name": "animals"
+  }]
+}
+```
 
-We currently support ruleset files in both `yaml` and `json` formats.
+While running it with this object, it will succeed:
+
+```json
+{
+  "tags": [{
+    "name": "animals",
+    "description": "come in all shapes and sizes"
+  }]
+}
+```
+
+### Adding to the recommended OpenAPI rules
+
+Spectral comes with two built in rulesets - one for OpenAPI v2 (`spectral:oas2`), and one for OpenAPI v3 (`spectral:oas3`). Use the `extends` property in your ruleset file to build upon or customize other rulesets.
+
+**spectral.yml**
 
 ```yaml
-extends:
-  - https://acme.com/ruleset.json
-  - /path/to/ruleset.yaml
+extends: spectral:oas2
 rules:
-    rule-name:
-        given: $..parameters[*]
-        then:
-            field: description
-            function: truthy
+  my-rule-name:
+    description: Tags must have a description.
+    given: $.tags[*]
+    then:
+      field: description
+      function: truthy
 ```
 
+The example above will apply the recommended rules from the built in OpenAPI v2 ruleset AND apply the custom `my-rule-name` rule.
+
+### Enabling specific OpenAPI rules
+
+Sometimes you might want to apply specific rules from another ruleset. Use the `extends` property, and pass `off` as the second argument in order to add the rules from another ruleset, but disable them all by default. This allows you to pick and choose which rules you would like to enable.
+
+**spectral.yml**
+
+```yaml
+extends: [[spectral:oas2, off]]
+rules:
+  # This rule is defined in the spectral:oas2 ruleset. We're passing `true` to turn it on and inherit the severity defined in the spectral:oas2 ruleset.
+  operation-operationId-unique: true
+```
+
+The example above will run the single rulee that we enabled, since we passed `off` to disable all rules by default when extending the `spectral:oas2` ruleset.
+
+### Disabling specific OpenAPI rules
+
+This example shows the opposite of the `Enabling specific OpenAPI rules` example. Sometimes you might want to enable all rules by default, and disable a few.
+
+**spectral.yml**
+
+```yaml
+extends: [[spectral:oas2, all]]
+
+rules:
+  operation-operationId-unique: false
+```
+
+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)
+
+### Changing the severity of a rule
+
+**spectral.yml**
+
+```yaml
+extends: spectral:oas2
+rules:
+  operation-2xx-response: warn
+```
+
+The example above will run the recommended rules from the `spectral:oas2` ruleset, but report `operation-2xx-response` as a warning rather than as an error (as is the default behavior in the `spectral:oas2` ruleset).
+
+Available severity levels are `error`, `warn`, `info`, `hint`, and `off`.
+
 ## Rules
 
 Rules are highly configurable. There are only few required parameters but the optional ones gives powerful flexibility. Please see the following type tables for more information.
 
-*TODO: generate this table automatically from the TS file.*
+<!-- *TODO: generate this table automatically from the TS file.* -->
 
 <table>
   <thead>
@@ -85,7 +173,7 @@ Rules are highly configurable. There are only few required parameters but the op
       <td>recommended</td>
       <td><code>boolean</code></td>
       <td>should the rule be enabled by default?</td>
-    </tr>        
+    </tr>
     <tr>
       <td>when</td>
       <td><code><a href="#when">When</a></code></td>
@@ -104,7 +192,7 @@ Rules are highly configurable. There are only few required parameters but the op
       <th>Description</th>
     </tr>
   </thead>
-  <tbody>    
+  <tbody>
     <tr>
       <td>function</td>
       <td><code>string</code></td>
@@ -114,7 +202,7 @@ Rules are highly configurable. There are only few required parameters but the op
       <td>field</td>
       <td><code>string</code></td>
       <td>Name of the field to narrow by or special <code>@key</code> value. If a field name is provided, the function will receive value of that field. If <code>@key</code> is provided, the function will receive its key.<br/>Example: if the target object is an oas object and given = <code>$..responses[*]</code>, then <code>@key</code> would be the response code (200, 400, etc) and <code>description</code> would be the value of each response's description</td>
-    </tr>    
+    </tr>
     <tr>
       <td>functionOptions</td>
       <td><code>Object</code></td>
@@ -133,7 +221,7 @@ Rules are highly configurable. There are only few required parameters but the op
       <th>Description</th>
     </tr>
   </thead>
-  <tbody>    
+  <tbody>
     <tr>
       <td>field</td>
       <td><code>string</code></td>
@@ -158,12 +246,12 @@ $ spectral lint some-oas.yaml --ruleset acme-company.json
 
 Reading ruleset
 
-/rules/rule-without-given-nor-them 	 should have required property 'given' 
-/rules/rule-without-given-nor-them 	 should have required property 'then' 
-/rules/rule-with-invalid-enum/severity 	 should be number 
-/rules/rule-with-invalid-enum/severity 	 should be equal to one of the allowed values 
-/rules/rule-with-invalid-enum/type 	 should be equal to one of the allowed values 
+/rules/rule-without-given-nor-them 	 should have required property 'given'
+/rules/rule-without-given-nor-them 	 should have required property 'then'
+/rules/rule-with-invalid-enum/severity 	 should be number
+/rules/rule-with-invalid-enum/severity 	 should be equal to one of the allowed values
+/rules/rule-with-invalid-enum/type 	 should be equal to one of the allowed values
 ```
 
-These errors should look just like errors you get from Spectral when an API description is invalid, 
-so use them to fix your rules in the same way.
+These errors should look just like errors you get from Spectral when an API description is invalid,
+so use them to fix your rules in the same way.