SchemaComparator

[ghik]

Required for https://github.com/softwaremill/tapir/issues/3645

SchemaComparator compares two schemas for compatibility and returns a list of SchemaCompatibilityIssues.

Currently, the comparator only understands a fixed set of common schema patterns, likely to be generated by tapir from common Scala types:

• trivial "any" and "nothing" schemas
• primitive schemas (containing type which is not object or array + simple assertions, e.g. minimum, maximum etc.)
• simple array types (type array with items + simple array assertions)
• tuple-like array types (type array with prefixItems + simple array assertions)
• map types (type object with additionalProperties + simple object assertions)
• product types (type object with properties, possible required and dependentRequired)
• discriminated coproduct types (no type, oneOf/anyOf with simple local references and discriminator)
• union types and non-discriminated coproduct types (no type, oneOf/anyOf, no discriminator)

The following JSON Schema keywords are currently not understood at all:

• $schema, $vocabulary, $id, $anchor, $anchor, $dynamicAnchor, $dynamicRef, $defs (maybe some of them can be ignored like annotations?)
• allOf, not (except in "nothing" schema)
• if, then, else
• contains, maxContains, minContains, unevaluatedItems
• patternProperties, unevaluatedProperties, dependentSchemas

If schemas don't fall into any of the above categories, or contain any of the mentioned unsupported keywords, they are considered opaque and compared only for plain equality (with annotations stripped). If they are not equal a generic "fallback" error is returned that indicates SchemaComparator's inability to determine compatibility between schemas (they may or may not be compatible).

[adamw]

The most important missing feature is comparison of undiscriminated unions expressed with anyOf or oneOf - this is tricky because matching elements of anyOf/oneOf between two schemas can turn into a combinatorial explosion of comparisons.

Let's start with the simplest thing that works, and then we can refine :) I think for a start a very simplistic matching of schemas listed in anyOf will work (for each each schema on the left, there is a compatible schema on the right).

[adamw]

Nice work - well beyond what I imagined originally, but very thorough :).