JSON validation

The Sensu docs have a JSON validator test run by Travis CI. The test is a Python script that looks for content inside of {{< code json >}}{{< /code >}} tags within all .md files in the content directory. The script then validates the content within the JSON code tags against the Python json library.

Place JSON-related log entries in shell tags {{< code shell >}}{{< /code >}} so that the validator will skip over them. If you use JSON tags for multi-line snippets without the usual JSON formatting, the Python JSON library will throw an error. Log entries will also retain their code look on the final documentation site.

Example:

{"timestamp":"2018-06-10T16:39:15.988000+0200","level":"warn","message":"transport connection error","reason":"tcp connection lost"}
{"timestamp":"2018-06-10T16:39:15.989000+0200","level":"warn","message":"transport connection error","reason":"possible authentication failure. wrong credentials?","user":"sensu"}

Some Sensu JSON blocks should use shell tags with a json syntax indicator {{< code shell "JSON" >}}{{< /code >}}. For example, several guides wrap JSON definitions inside cat << EOF | sensuctl create and EOF commands for a complete command that users can copy with one click. These definitions use valid JSON but the added commands will cause the test to fail in the Python library.

You can see the results of the Travis CI checks in each pull request. To see errors detected by the JSON validator, open the Travis CI check details for the pull request.

Ideas for improving the JSON validation

• Add original file line numbers to JSON output so users can find their issue faster. Use a find to locate them for now.
• Possibly move the script to another language that has a json library that plays nicer with our doc code base (Go or Ruby?)