From af5fe64c398c9bd4206c3c6c1ade81768b291031 Mon Sep 17 00:00:00 2001 From: Adam Jones Date: Tue, 25 Apr 2023 12:20:55 +0100 Subject: [PATCH] docs: Fix custom rule schema docs (#17115) * docs: Fix custom rule schema docs * Address review feedback --- docs/src/extend/custom-rules.md | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/docs/src/extend/custom-rules.md b/docs/src/extend/custom-rules.md index 0ea6f7e75bb..8484a59b140 100644 --- a/docs/src/extend/custom-rules.md +++ b/docs/src/extend/custom-rules.md @@ -608,12 +608,17 @@ You can also access comments through many of `sourceCode`'s methods using the `i Rules may export a `schema` property, which is a [JSON Schema](https://json-schema.org/) format description of a rule's options which will be used by ESLint to validate configuration options and prevent invalid or unexpected inputs before they are passed to the rule in `context.options`. -There are two formats for a rule's exported `schema`. The first is a full JSON Schema object describing all possible options the rule accepts, including the rule's error level as the first argument and any optional arguments thereafter. +There are two formats for a rule's exported `schema`: -However, to simplify schema creation, rules may also export an array of schemas for each optional positional argument. ESLint automatically validates the required error level first. For example, the `yoda` rule accepts a primary mode argument, as well as an extra options object with named properties. +1. A full JSON Schema object describing all possible options the rule accepts. +2. An array of JSON Schema objects for each optional positional argument. + +In both cases, these should exclude the [severity](../use/configure/rules#rule-severities), as ESLint automatically validates this first. + +For example, the `yoda` rule accepts a primary mode argument of `"always"` or `"never"`, as well as an extra options object with an optional property `exceptRange`: ```js -// "yoda": [2, "never", { "exceptRange": true }] +// "yoda": ["error", "never", { "exceptRange": true }] module.exports = { meta: { schema: [ @@ -634,12 +639,10 @@ module.exports = { }; ``` -In the preceding example, the error level is assumed to be the first argument. It is followed by the first optional argument, a string that may be either `"always"` or `"never"`. The final optional argument is an object, which may have a boolean property named `exceptRange`. - -To learn more about JSON Schema, we recommend looking at some examples in [website](https://json-schema.org/learn/) to start, and also reading [Understanding JSON Schema](https://json-schema.org/understanding-json-schema/) (a free ebook). - **Note:** If your rule schema uses JSON schema [`$ref`](https://json-schema.org/understanding-json-schema/structuring.html#ref) properties, you must use the full JSON Schema object rather than the array of positional property schemas. This is because ESLint transforms the array shorthand into a single schema without updating references that makes them incorrect (they are ignored). +To learn more about JSON Schema, we recommend looking at some examples on the [JSON Schema website](https://json-schema.org/learn/), or reading the free [Understanding JSON Schema](https://json-schema.org/understanding-json-schema/) ebook. + ### Accessing Shebangs [Shebangs (#!)](https://en.wikipedia.org/wiki/Shebang_(Unix)) are represented by the unique tokens of type `"Shebang"`. They are treated as comments and can be accessed by the methods outlined in the [Accessing Comments](#accessing-comments) section, such as `sourceCode.getAllComments()`.