docs(repo): adds json formatter docs

docs/guides/2-cli.md

@@ -70,6 +70,111 @@ The default behavior can be modified with the `--fail-severity=` option. Setting
 
 Changing the fail severity wont' affect output. To change the results Spectral CLI prints to the screen, add the `--display-only-failures` switch (or just `-D` for short). This removes any results which are below the specified fail severity.
 
+## Formatters
+
+### JSON Formatter
+
+Spectral's JSON formatter outputs the results of a Spectral analysis in a JSON format that is easily parsable and human-readable. The output can be used to programmatically access and process the results of the analysis. You can enable this by adding `-f json --quiet` to the cli command.
+
+Here's the schema for the output:
+
+<!--
+type: tab
+title: Schema
+-->
+
+```yaml json_schema
+type: array
+items:
+  type: object
+  properties:
+    code:
+      type: string
+      description: A string that represents the rule code that has been violated or triggered in Spectral. This code is unique to each rule defined in Spectral.
+    path:
+      type: array
+      description: An array of strings that indicate the location within the analyzed document where the rule was triggered. It shows the "path" in the document structure to the issue.
+      items:
+        type: string
+    message:
+      type: string
+      description: A string that contains a human-readable message describing the issue found by Spectral. This message typically provides information on why the rule was triggered and how to fix the issue.
+    severity:
+      enum:
+        - 0
+        - 1
+        - 2
+        - 3
+      description: An integer representing the severity level of the rule violation. The severity levels usually follow a specific scale defined by Spectral. 0 equals error, while 3 is hint.
+    range:
+      type: object
+      description: An object that describes where in the file the issue was found. It contains two sub-properties, start and end, each of which is an object with line and character properties. line and character are integers that represent the line number and the character position within the line, respectively, where the issue starts or ends. All the values are zero indexed.
+      properties:
+        start:
+          type: object
+          properties:
+            line:
+              type: integer
+              minimum: 0
+            character:
+              type: integer
+              minimum: 0
+          required:
+            - line
+            - character
+        end:
+          type: object
+          properties:
+            line:
+              type: integer
+              minimum: 0
+            character:
+              type: integer
+              minimum: 0
+          required:
+            - line
+            - character
+    source:
+      type: string
+      description: A string that contains the file path of the document that was analyzed by Spectral. It points to the source of the issue.
+  required:
+    - code
+    - path
+    - message
+    - severity
+    - range
+    - source
+```
+
+<!--
+type: tab
+title: Example
+-->
+
+```json
+[
+  {
+    "code": "invalid-response",
+    "path": ["paths", "/users/{id}", "get", "responses", "200"],
+    "message": "The '200' response should include a schema definition.",
+    "severity": 2,
+    "range": {
+      "start": {
+        "line": 32,
+        "character": 12
+      },
+      "end": {
+        "line": 35,
+        "character": 14
+      }
+    },
+    "source": "/Users/johndoe/projects/api-definition/openapi.yaml"
+  }
+]
+```
+
+<!-- type: tab-end -->
+
 ## Proxying
 
 To have requests made from Spectral be proxied through a server, you'd need to specify the `PROXY` environment variable: