From 9270513f14c76e81ac7bb37a77d6a5005ae0942a Mon Sep 17 00:00:00 2001
From: David Anson <david@dlaa.me>
Date: Sun, 26 Nov 2023 20:10:31 -0800
Subject: [PATCH] Add instructions for "Validating Configuration" to explain
 how to use the JSON Schema with configuration objects/files.

---
 README.md                         |  3 +++
 schema/ValidatingConfiguration.md | 28 ++++++++++++++++++++++++++++
 test/markdownlint-test.js         |  2 +-
 3 files changed, 32 insertions(+), 1 deletion(-)
 create mode 100644 schema/ValidatingConfiguration.md

diff --git a/README.md b/README.md
index 6feb0eb3..9eb2eb5a 100644
--- a/README.md
+++ b/README.md
@@ -377,6 +377,9 @@ See [.markdownlint.jsonc](schema/.markdownlint.jsonc) and/or
 [.markdownlint.yaml](schema/.markdownlint.yaml) for an example
 configuration object with all properties set to the default value.
 
+See [ValidatingConfiguration.md](schema/ValidatingConfiguration.md) for ways to
+validate configuration.
+
 Sets of rules (known as a "style") can be stored separately and loaded
 as [JSON](https://en.wikipedia.org/wiki/JSON).
 
diff --git a/schema/ValidatingConfiguration.md b/schema/ValidatingConfiguration.md
new file mode 100644
index 00000000..f6ae6a5b
--- /dev/null
+++ b/schema/ValidatingConfiguration.md
@@ -0,0 +1,28 @@
+# Validating Configuration
+
+A [JSON Schema][json-schema] is provided to enable validating configuration
+objects: [`markdownlint-config-schema.json`][markdownlint-config-schema]
+
+Some editors automatically use a JSON Schema with files that reference it. For
+example, a `.markdownlint.json` file with:
+
+```json
+"$schema": "https://raw.githubusercontent.com/DavidAnson/markdownlint/main/schema/markdownlint-config-schema.json"
+```
+
+A JSON Schema validator can be used to check configuration files like so:
+
+```bash
+npx ajv-cli validate -s ./markdownlint/schema/markdownlint-config-schema.json -d "**/.markdownlint.{json,yaml}" --strict=false
+```
+
+By default, any rule name is valid in order to allow for custom rules. To ensure
+that only built-in rules are used, change the value of `#/additionalProperties`
+(at the bottom of the schema file) to `false` before validating:
+
+```json
+"additionalProperties": false
+```
+
+[json-schema]: https://json-schema.org
+[markdownlint-config-schema]: markdownlint-config-schema.json
diff --git a/test/markdownlint-test.js b/test/markdownlint-test.js
index 8e453ba2..4530bf8f 100644
--- a/test/markdownlint-test.js
+++ b/test/markdownlint-test.js
@@ -83,7 +83,7 @@ test("projectFiles", (t) => {
       "schema/*.md"
     ]))
     .then((files) => {
-      t.is(files.length, 57);
+      t.is(files.length, 58);
       const options = {
         files,
         "config": require("../.markdownlint.json")