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

[github-actions]

Welcome to AsyncAPI. Thanks a lot for reporting your first issue. Please check out our contributors guide and the instructions about a basic recommended setup useful for opening a pull request.
Keep in mind there are also other channels you can use to interact with AsyncAPI community. For more details check out this issue.

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience ❤️

[dlkj]

cough

No comments?

Would anyone have any objection to me prototyping this and creating a PR?

[jonaslagoni]

I dont think no one is @dlkj, it's open source for a reason, so go ahead and champion what you wish to see!

If you want feedback I would suggest pinging the code owner https://github.com/asyncapi/diff/blob/master/CODEOWNERS, or try out in slack as well 👍

[dlkj]

Thanks. I just like to get a feel of the community's feelings about things before making a substantial PR and risk having it rejected because it doesn't align well with the core team's vision for the project.

[jonaslagoni]

Understandable, also why I am suggesting you ping the code owners, don't wait months, a week or two is enough before you follow up, and just continue to do so.

There can be many reasons why they haven't gotten back to you, so it's all about being active about it 🙂

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience ❤️

[Papooch]

I would also be interested in this feature. The current detection of breaking/non-breaking changes is insufficient for most common scenarios - e.g. changing the payload of messages in terms of adding/removing required/optional properties, which have a more nuanced semantics. I'll see if I find time to draft a PR.