You can also create your own rulesets with a simple `.json` file.
+You can also create your own rulesets with a simple `.yaml` file.
diff --git a/docs/rules/2-custom-rulesets.md b/docs/rules/2-custom-rulesets.md index a66f088b..05b0453c 100644 --- a/docs/rules/2-custom-rulesets.md +++ b/docs/rules/2-custom-rulesets.md @@ -12,66 +12,30 @@ Let's define some terminology: ### Ruleset file format -A rules file is a JSON formatted file, containing an object with a `rules` property, which is an array of rule objects. +A rules file is a YAML or JSON file containing an object with a `rules` property, which is an array of rule objects. There is a reserved `require` property (type `string`) at the top level, which can be used for ruleset chaining. #### Example -```json -{ - "require" : "default", - "rules" : [ - { - "name": "openapi-tags", - "object": "openapi", - "enabled": true, - "description": "openapi object should have non-empty tags array", - "truthy": "tags" - }, - { - "name": "default-and-example-are-redundant", - "object": "*", - "enabled": true, - "description": "don't need to define an example if its exactly the same as your default", - "notEqual": ["default", "example"] - } - ] -} +```yaml +require: default +rules: +- name: openapi-tags + object: openapi + description: "openapi object should have non-empty tags array" + truthy: tags +- name: default-and-example-are-redundant + object: "*" + description: "don't need to define an example if its exactly the same as your default" + notEqual: ["default", "example"] ``` -### Rule object format +Since v0.9.0, Speccy uses [oas-linter], which is part of [oas-kit] by [Mike Ralphson]. -|Property|Type|Required|Description| -|---|---|---|---| -|name|string|yes|The name/slug of the rule. Use hyphens. Used as the unique key. You can namespace your rules with any prefix and delimiter you wish, to avoid clashes with other people's and the built-in rules| -|description|string|recommended|An optional description for the rule| -|enabled|boolean|no|Set to `false` to temporarily disable a rule| -|object|string\|array|no|The object(s) to act upon, may be `*` for all objects. E.g. `parameter`| -|truthy|string\|array|no|A property or list of properties which must be truthy (present with a non-false, non-null, non-empty value). Empty arrays are not considered truthy| -|alphabetical|object|reserved|Makes sure values are in alphabetical order. Structure: `{ properties: string, keyedBy: string }`| -|or|array|no|An array of property names, one or more of which must be present| -|maxLength|object|reserved|An object containing a `property` string name, and a `value` (integer). The length of the `property` value must not be longer than `value`| -|notContain|object|no|An object containing a `properties` array and either a `value` (case-sensitive string matches) or `pattern` (full regex matching). If using `value`, none of the `properties` must contain the `value`. If using `pattern`, you should supply `pattern.value` which contains your regex. If you wish to also supply additional flags, you can do so on `pattern.flags`.| -|notEndWith|object|no|An object containing a `property`, an optional `omit` prefix and a `value` string. The given `property` (once `omit` is removed) must not end with the given `value`. Used with strings| -|notEquals|object|no|An array containing a list of property names, which must have different values if present| -|pattern|object|no|An object containing a `property` name, an optional `split` string which is used to split the value being tested into individual components, an optional `omit` string (which is chopped off the front of each component being tested), and a `value` regex property which is used to test all components of the property value being tested| -|properties|integer|no|The exact number of non-extension properties which must be present on the target object| -|skip|string|no|The name of a property in the `options` object. If this property is truthy, then the rule is skipped. E.g. `isCallback` can be used to skip rules for `operation` objects within `callback` objects, while still applying to top-level `operation` objects| -|xor|array|no|An array of property names, only one of which must be present| +See the [full list of rule actions][linter-rules] available to be used in your rulesets. -