Extend overrides with callbacks to support more complex breaking change detection

[dlkj]

Reason/Context

Please try answering few of those questions

• Why we need this improvement?
• How will this change help?
• What is the motivation?

The current overrides functionality provides a simple way to classify the addition, removal or edit of a JsonPath as non-breaking, breaking or unclassified. I'd like to be able to extend diff to classify changes to message payloads and classify these as non-breaking, breaking or unclassified.

As AsyncAPI supports arbitrary payload formats, classifying changes can be arbitrarily complex. For example, to classify a change to JsonSchema, one would need to detect the addition or removal of schema properties and also whether those properties are required. This is technically achievable using extension to JsonPath, such as complex filters, this becomes quickly cumbersome and error prone.

This would also have applications outside of the message payload.

Description

Please try answering few of those questions

• What changes have to be introduced?
• Will this be a breaking change?
• How could it be implemented/designed?

Strawman design:

• Extend overrides so that add, remove and edit could also take a callback value as well as the existing strings:

overrides: {
  "/servers/*/protocol": {
    add: addProtocolCallback,
    remove: "breaking",
    edit: editProtocolCallback,
  },
}

• Optionally extend overrides so that a single callback can be used to evaluate any change to a jsonPath:

overrides: {
  "/servers/*/protocol": protocolCallback,
},

• The call back should take the following arguments:
  • firstDocumentFragment - the subtree of the first document from the jsonPath
  • secondDocumentFragment - the subtree of the second document from the jsonPath
  • context
    • firstDocument - first document root
    • secondDocument - second document root
    • path - the JsonPointer to the current instance of the override rule
    • operation - one of "add", "remove" and "edit"
• The call back should return one of: "non-breaking", "breaking" and "unclassified"

This would be a non breaking change.

Inspiration could be taken from spectral's custom functions