Documentation Rewrite

README.md

@@ -14,14 +14,12 @@ A flexible JSON linter with out of the box support for OpenAPI v2 and v3.
 - 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.
+- Built-in set of functions to help [create custom rules][add-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 for advanced use cases
-- Validate JSON with [Ajv](https://www.npmjs.com/package/ajv)
+- Validate JSON with [Ajv][ajv]
 
 ## Installation
 
-Spectral's CLI can be installed via npm or yarn.
-
 ```bash
 npm install -g @stoplight/spectral
 
@@ -30,78 +28,37 @@ npm install -g @stoplight/spectral
 yarn global add @stoplight/spectral
 ```
 
-Spectral is avaiable as a Docker image as well
-
-```bash
-docker run --rm -it stoplight/spectral lint "${url}"`
-```
-
-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
-
-```bash
-docker run --rm -it -v $(pwd):/tmp stoplight/spectral lint "/tmp/file.yaml"
-```
-
-Finally, [executable binaries](#executable-binaries) are also available.
-
-## Usage
-
-### CLI
-
-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.
-
-### Examples
+For more installation options, see [Getting Started > Installation][install]
 
-- [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)
+## Getting Started
 
-## Concepts
+After [installation][install] take a look at our [getting started documentation][get-started].
 
-There are three key concepts in Spectral: **Rulesets**, **Rules**, and **Functions**.
-
-- **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 **Spectral ruleset** as a flexible and customizable style guide for your JSON objects.
-
-## Programmatic usage
-
-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).
+- [Adding a rule][add-rule]
+- [Extending rulesets][extending-rulesets]
+- [Enable only specific rules][enable-rule]
+- [Disable specific rules][disable-rules]
+- [Changing the severity of a rule][change-severity]
+- [Using the JavaScript API][js-api]
 
 ## FAQs
 
-#### How is this different than [Ajv](https://www.npmjs.com/package/ajv)?
+### How is this different to 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.
+[Ajv][ajv] is a JSON Schema validator, and Spectral is a JSON/YAML linter. Instead of just validating against JSON Schema, it can be used to write rules for any sort of JSON/YAML object, which could be JSON Schema, or OpenAPI, or anything similar. Spectral does expose a [`schema` function][ref-funcs] that you can use in your rules to validate all or part of the target object with JSON Schema (we even use Ajv used under the hood for this), but that's just one of many functions.
 
-#### 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)?
-
-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
+### What is the difference between Spectral and Speccy
 
-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.
+[Speccy](https://github.com/wework/speccy) was a great inspiration for Spectral, but was designed to work only with OpenAPI v3. Spectral can apply rules to _any_ JSON/YAML object (including OpenAPI v2 and v3) through the use of [JSONPath](http://goessner.net/articles/JsonPath/) `given` parameters. 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 functions, and we've added the ability to define custom functions too.
 
 ## Contributing
 
 If you are interested in contributing to Spectral itself, check out our [contributing docs](CONTRIBUTING.md) to get started.
 
-Also, most of the interesting projects are built _with_ Spectral. Please consider using Spectral in a project or contribute to an [existing one](#example-implementations).
-
 If you are using Spectral in your project and want to be listed in the examples section, we encourage you to open an [issue](https://github.com/stoplightio/spectral/issues).
 
 ### Example Implementations
@@ -112,19 +69,30 @@ If you are using Spectral in your project and want to be listed in the examples
 
 ## Helpful Links
 
-- [JSONPath Online Evaluator](http://jsonpath.com/), a helpful tool to determine what `path` you want
+- [JSONPath Online Evaluator](http://jsonpath.com/), a helpful tool to determine what `given` path you want
 - [stoplightio/json](https://github.com/stoplightio/json), a library of useful functions for when working with JSON
 - [stoplightio/yaml](https://github.com/stoplightio/yaml), a library of useful functions for when working with YAML, including parsing YAML into JSON, and a few helper functions such as `getJsonPathForPosition` or `getLocationForJsonPath`
 
 ## Thanks :)
 
 - [Phil Sturgeon](https://github.com/philsturgeon) for collaboration and creating Speccy
-- [Mike Ralphson](https://github.com/MikeRalphson) for kicking off the Spectral CLI
+- [Mike Ralphson](https://github.com/MikeRalphson) for kicking off the Spectral CLI and his work on Speccy
 
 ## Support
 
-If you have a bug or feature request, please open an issue [here](https://github.com/stoplightio/spectral/issues).
+If you have a bug or feature request, please [create an issue](https://github.com/stoplightio/spectral/issues).
 
 If you need help using Spectral or have a support question, please use the [Stoplight Community forum](https://community.stoplight.io). We've created an open source category for these questions. It's also a great place to share your implementations.
 
 If you want to discuss something in private, you can reach out to Stoplight support at [support@stoplight.io](mailto:support@stoplight.io).
+
+[ajv]: https://www.npmjs.com/package/ajv
+[get-started]: https://stoplight.io/p/docs/gh/stoplightio/spectral/docs/getting-started/concepts.md
+[ref-funcs]: https://stoplight.io/p/docs/gh/stoplightio/spectral/docs/reference/functions.md
+[add-rule]: https://stoplight.io/p/docs/gh/stoplightio/spectral/docs/getting-started/rulesets.md#adding-a-rule
+[extending-rulesets]: https://stoplight.io/p/docs/gh/stoplightio/spectral/docs/getting-started/rulesets.md#extending-rules
+[enable-rules]: https://stoplight.io/p/docs/gh/stoplightio/spectral/docs/getting-started/rulesets.md#enable-rules
+[disable-rules]: https://stoplight.io/p/docs/gh/stoplightio/spectral/docs/getting-started/rulesets.md#disable-rules
+[change-severity]: https://stoplight.io/p/docs/gh/stoplightio/spectral/docs/getting-started/rulesets.md#changing-severity-of-a-rule
+[js-api]: https://stoplight.io/p/docs/gh/stoplightio/spectral/docs/guides/javascript.md
+[install]: https://stoplight.io/p/docs/gh/stoplightio/spectral/docs/getting-started/installation.md

docs/getting-started/concepts.md

@@ -0,0 +1,27 @@
+# Concepts
+
+The power of integrating linting into the design-first workflow, or any workflow which involves API descriptions, is often overlooked.
+
+Linting is not just about checking to see if you OpenAPI or JSON Schema documents are technically correct according to the specifications, they are for enforcing style guides! These style guides, much like eslint, can help catch a lot more than just "invalid syntax".
+
+To achieve this functionality, Spectral has three key concepts: "Rulesets", "Rules", and "Functions".
+
+- **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.
+
+Rules can be comprised of one of more functions, to facilitate any style guide.
+
+- HTTP Basic is not allowed at this company
+- Are all operations secured with a security schema
+- Descriptions must not contain Markdown
+- Tags must be plural
+- Tags must be singular
+
+Spectral comes bundled with a [bunch of functions][ref-funcs] and a default style guide for [OpenAPI v2 and v3][openapi], which you can extend, cherry-pick, or disable entirely. 
+
+Learn more about [rulesets][rulesets]. 
+
+[ref-funcs]: https://stoplight.io/p/docs/gh/stoplightio/spectral/docs/reference/functions.md
+[rulesets]: https://stoplight.io/p/docs/gh/stoplightio/spectral/docs/guides/rulesets.md
+[openapi]: https://stoplight.io/p/docs/gh/stoplightio/spectral/docs/guides/openapi.md

docs/getting-started/installation.md

@@ -0,0 +1,38 @@
+
+# Installation
+
+For many, the easiest way to install Spectral is as a node module. 
+
+```bash
+npm install -g @stoplight/spectral
+```
+
+If you are a Yarn user:
+
+```bash
+yarn global add @stoplight/spectral
+```
+
+## Executable binaries
+
+For users without Node and/or NPM/Yarn, we provide standalone packages for [all major platforms](https://github.com/stoplightio/spectral/releases). The quickest way to install the appropriate package for your operating system is via this shell script:
+
+```bash
+curl -L https://raw.githack.com/stoplightio/spectral/master/install.sh | sh
+```
+
+Note, the binaries do _not_ auto-update, so you will need to run it again to install new versions.
+
+## Docker
+
+Spectral is also available as a Docker image, which can be handy for all sorts of things, like if you're contributing code to Spectral, want to integrate it into your CI build.
+
+```bash
+docker run --rm -it stoplight/spectral lint "${url}"`
+```
+
+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
+
+```bash
+docker run --rm -it -v $(pwd):/tmp stoplight/spectral lint "/tmp/file.yaml"
+```

docs/getting-started/openapi.md

@@ -0,0 +1,9 @@
+# OpenAPI Support
+
+Spectral is a generic linter, but a lot of effort has been put in to making sure OpenAPI is well supported. 
+
+Run Spectral against a document without specifying a ruleset will trigger an auto-detect, where Spectral will look to see if `swagger: 2.0` or `openapi: 3.0.x` is at the top of the file. If it finds either of those it will load `spectral:oas2` or `spectral:oas3`, both of which are documented in our [Reference > OpenAPI Rules][openapi-rules].
+
+_**Note:** If you would like support for other API description formats like RAML, message formats like JSON:API, or anything at all, we recommend you start building up custom, but generic rulesets that can be shared with others. These can then be shared around in a sort of marketplace in the future._
+
+[openapi-rules]: https://stoplight.io/p/docs/gh/stoplightio/spectral/docs/reference/openapi-rules.md

docs/getting-started/rulesets.md

@@ -0,0 +1,147 @@
+# Spectral Rulesets
+
+Rulesets are collections of rules, in a YAML or JSON file. These rules are taking parameters, and calling functions on certain parts of another YAML or JSON object being linted. 
+
+### Adding a rule
+
+Add your own rules under the `rules` property in your `.spectral.yml` ruleset file.
+
+```yaml
+rules:
+  my-rule-name:
+    description: Tags must have a description.
+    given: $.tags[*]
+    severity: error
+    then:
+      field: description
+      function: truthy
+```
+
+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"
+  }]
+}
+```
+
+While running it with this object, it will succeed:
+
+```json
+{
+  "tags": [{
+    "name": "animals",
+    "description": "come in all shapes and sizes"
+  }]
+}
+```
+
+### Severity
+
+The `severity` keyword is optional and can be `error`, `warn`, `info`, or `hint`.
+
+### Then
+
+The Then part of the rules explains what to do with the `given` JSON Path, and involves two required keywords:
+
+```yaml
+  then:
+    field: description
+    function: truthy
+```
+
+The `field` keyword is optional, and is for applying the function to a specific property in an object. If omitted the function will be applied to the entire target of the `given` JSON Path. The value can also be `@key` to apply the rule to a keys of an object.
+
+```yaml
+given: '$.responses'
+then:
+  field: '@key'
+  function: pattern
+  functionOptions:
+    match: '^[0-9]+$' 
+```
+
+The above pattern based rule would error on `456avbas` as it is not numeric.
+
+```yaml
+responses:
+  123:
+    foo: bar
+  456avbas:
+    foo: bar
+```
+
+### Extending Rules
+
+Rulesets can extend other rulesets. For example, 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.
+
+```yaml
+extends: spectral:oas2
+rules:
+  my-rule-name:
+    description: Tags must have a description.
+    given: $.tags[*]
+    then:
+      field: description
+      function: truthy
+```
+
+The example above will apply the core rules from the built in OpenAPI v2 ruleset AND apply the custom `my-rule-name` rule. 
+
+Extends can be a single string or an array of strings, and can contain either local file paths or URLs.
+
+```yaml
+extends: 
+- ./config/spectral.json
+- https://example.org/api/style.yaml
+```
+
+### Enable 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.
+
+```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 rule that we enabled, since we passed `off` to disable all rules by default when extending the `spectral:oas2` ruleset.
+
+### Disable Rules
+
+This example shows the opposite of the "Enabling Specific rules" example. Sometimes you might want to enable all rules by default, and disable a few.
+
+```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 only 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 rulesets:
+
+- [Rules relevant to both OpenAPI v2 and v3](https://github.com/stoplightio/spectral/tree/develop/src/rulesets/oas/index.json)
+- [Rules specific to only OpenAPI v2](https://github.com/stoplightio/spectral/tree/develop/src/rulesets/oas2/index.json)
+- [Rules specific to only OpenAPI v3](https://github.com/stoplightio/spectral/tree/develop/src/rulesets/oas3/index.json)
+
+### Changing Severity of a Rule
+
+```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`.

docs/cli.md → docs/guides/cli.md

@@ -17,9 +17,8 @@ Other options include:
   -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).
+Currently, Spectral CLI supports validation of OpenAPI v2/v3 documents via our built-in ruleset, or you can create [custom rulesets](./rulesets.md) to work with any JSON/YAML documents.