json-schema-misconfigurations

JSON Schema misconfigurations

Authors:

• 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.

  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.

  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.

  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.

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).