Breaking Changes with AllOf
OpenAPI 3.0 provides several keywords which can be used to combine schemas.
You can use these keywords to create a complex schema or validate a value against multiple criteria.
oneOf – validates the value against exactly one of the subschemas
allOf – validates the value against all the subschemas
anyOf – validates the value against any (one or more) of the subschemas
Using these keywords can be useful to describe complex data models but it complicates breaking changes detection.
Consider, for example, the following comparison of two OpenAPI specs:
The result shows one breaking change which is due to a new subschema that was added under allOf which oasdiff considers naïvely as a new constraint which may be breaking.
But, in fact, the new subschema, highlighted below, doesn't add any new constraints, because it is identical to a previously existing subschema, and, as such, this isn't a breaking chanage.
allOf:
- type: object
properties:
prop1:
type: string
- type: object
properties:
prop2:
type: boolean
- type: object
properties:
prop1:
type: string
In order to eliminate such false-positives, oasdiff supports the ability to replace allOf by a merged equivalent before comparing the specs, like this:
With the 'flatten' flag, no breaking changes are reported, correctly.
In order to see how oasdiff merges allOf, you can use the 'flatten' subcommand which flattens an OpenAPI spec: