diff --git a/README.md b/README.md index 5544c6a..c95c2ce 100644 --- a/README.md +++ b/README.md @@ -43,6 +43,7 @@ There are some fantastic examples of [configurable rules](https://redocly.com/do - [Paths should not match a pattern](configurable-rules/path-excludes-pattern/) - [API healthcheck rules](configurable-rules/api-health/) - [String schemas length defined](configurable-rules/string-schemas-length-defined/) +- [JSON Schema misconfigurations](configurable-rules/json-schema-misconfigurations/) ### Custom plugins diff --git a/configurable-rules/json-schema-misconfigurations/README.md b/configurable-rules/json-schema-misconfigurations/README.md new file mode 100644 index 0000000..b2398ff --- /dev/null +++ b/configurable-rules/json-schema-misconfigurations/README.md @@ -0,0 +1,113 @@ +# JSON Schema misconfigurations + +Authors: +- [`adamaltman`](https://github.com/adamaltman) Adam Altman (Redocly) + +## What this does and why + +This catches common misconfigurations of JSON Schema: +- disallows `minimum` or `maximum` values for a string (these are more logical for a number) +- disallows `items` on an object (instead of an array) +- disallows `properties` on an array (instead of items) + +## Code + +The first rule checks that a string isn't using the `minimum` and `maximum` keywords. +```yaml + rule/json-schema-string-misconfiguration: + subject: + type: Schema + where: + - subject: + type: Schema + property: type + assertions: + const: string + assertions: + disallowed: + - minimum + - maximum +``` + +The second rule checks that an array isn't using the `properties` keyword. +```yaml + rule/json-schema-array-misconfiguration: + subject: + type: Schema + where: + - subject: + type: Schema + property: type + assertions: + const: array + assertions: + disallowed: + - properties +``` + +The third rule checks that an object isn't using the `items` keyword. +```yaml + rule/json-schema-object-misconfiguration: + subject: + type: Schema + where: + - subject: + type: Schema + property: type + assertions: + const: object + assertions: + disallowed: + - items +``` + +## Examples + +The following OpenAPI has schemas prefixed with either `Good` or `Bad` to show the configurable rules catch the likely bad uses of keywords. + +```yaml +openapi: 3.1.0 +info: + title: Unintended schema misconfigurations + version: 1.0.0 +paths: {} +components: + schemas: + + BadString: + type: string + minimum: 5 + maximum: 10 + + GoodNumber: + type: number + minimum: 5 + maximum: 10 + + GoodString: + type: string + minLength: 5 + maxLength: 10 + + BadObject: + type: object + items: + type: string + + GoodObject: + type: object + properties: + foo: + $ref: "#/components/schemas/GoodString" + + BadArray: + type: array + properties: + foo: + $ref: "#/components/schemas/GoodString" +``` + + +## References + +Inspired by a question in the "APIs You Won't Hate" Slack community (special thanks to Can Vural and Phil Sturgeon). diff --git a/configurable-rules/json-schema-misconfigurations/openapi.yaml b/configurable-rules/json-schema-misconfigurations/openapi.yaml new file mode 100644 index 0000000..ee90471 --- /dev/null +++ b/configurable-rules/json-schema-misconfigurations/openapi.yaml @@ -0,0 +1,39 @@ +openapi: 3.1.0 +info: + title: Unintended schema misconfigurations + version: 1.0.0 +paths: {} +components: + schemas: + + BadString: + type: string + minimum: 5 + maximum: 10 + + GoodNumber: + type: number + minimum: 5 + maximum: 10 + + GoodString: + type: string + minLength: 5 + maxLength: 10 + + BadObject: + type: object + items: + type: string + + GoodObject: + type: object + properties: + foo: + $ref: "#/components/schemas/GoodString" + + BadArray: + type: array + properties: + foo: + $ref: "#/components/schemas/GoodString" diff --git a/configurable-rules/json-schema-misconfigurations/redocly.yaml b/configurable-rules/json-schema-misconfigurations/redocly.yaml new file mode 100644 index 0000000..5865ed1 --- /dev/null +++ b/configurable-rules/json-schema-misconfigurations/redocly.yaml @@ -0,0 +1,38 @@ +rules: + rule/json-schema-string-misconfiguration: + subject: + type: Schema + where: + - subject: + type: Schema + property: type + assertions: + const: string + assertions: + disallowed: + - minimum + - maximum + rule/json-schema-array-misconfiguration: + subject: + type: Schema + where: + - subject: + type: Schema + property: type + assertions: + const: array + assertions: + disallowed: + - properties + rule/json-schema-object-misconfiguration: + subject: + type: Schema + where: + - subject: + type: Schema + property: type + assertions: + const: object + assertions: + disallowed: + - items