schema linter

[karenetheridge]

It has been brought up on slack that a "lint" feature would be useful - this would look for potential problems in as schema that, while they are legal syntax, are generally nonsensical constructs. This would include missing keywords, or keywords used in strange combinations with each other.

From @ssilverman:

• minContains -> contains missing
• maxContains -> contains missing
• Unknown format value
• I think that all of the properties keywords can be independent, so additionalProperties without a properties, for instance, is valid. Maybe that's a "maybe warning" instead of a "full warning".
• Empty items, if array
• additionalItems -> non-array items
• unevaluatedItems -> non-array items
• Mismatched keywords or structure for schema. Examples:
  • Plain name fragments in $id for Draft 2019-09
  • Unknown formats
• Mixing old names with new names having the same purpose, for example definitions and $defs

my additions:

• unknown keywords in general
• $ref used as a property name rather than a keyword (this will of course produce a false positive in metaschemas)
• $schema used in a subschema where there is not an $id (this should perhaps be promoted into the metaschema itself)

@notEthan's ideas (warnings, not errors):

• maxContains has no effect without adjacent contains keyword
• minContains has no effect without adjacent contains keyword
• then has no effect without adjacent if keyword
• else has no effect without adjacent if keyword
• additionalItems has no effect without adjacent items keyword

[karenetheridge]

see also this thread. https://app.slack.com/client/T5CHC2TAN/CT8QRGTK5/thread/CT8QRGTK5-1589687250.289900

thread captured here before the scrollback vanishes: https://www.dropbox.com/s/w08yp1u8ziu8wqh/Screen%20Shot%202021-07-19%20at%2009.24.10.png?dl=0

[karenetheridge]

my additions part 2:

• 'default' annotation values that do not pass validation against the local subschema

[karenetheridge]

• 'default' keyword appearing under a property defined in 'properties', or in an element under 'items' (if the property/item is missing, the annotation will never be provided -- 'default' is more properly placed adjacent to a 'type: object' or 'type: string' (as a sibling to 'properties'/'items', not a child)

(and if the type of an instance is restricted to things that aren't object or array, 'default' makes no sense at all, because a missing item will never get the annotation - it only makes sense for non-scalar types)

[karenetheridge]

xref https://github.com/json-schema-org/json-schema-spec/issues/1079

[gregsdennis]

also xref https://github.com/orgs/json-schema-org/discussions/323

[karenetheridge]

• keywords that will never be evaluated given a prior constraint on the type - e.g. properties adjacent to a type: string

[karenetheridge]

and see the additions we can do for openapi linting: https://github.com/karenetheridge/OpenAPI-Modern/issues/59