Discussion on the `diff` generator

[aayushmau5]

In order to generate the difference between two JSON data, either we can use an existing library or implement our own JSON diffing library, but before we make that decision, I think it's important that we look at some great existing JSON diffing libraries.
If none of them work according to our needs, then can look into implementing our own.

After looking at some most popular as well as some most suitable libraries, I came up with these diffing libraries:

1. https://github.com/flitbit/diff (deep-diff)
2. https://github.com/andreyvit/json-diff (diff)
3. https://github.com/benjamine/jsondiffpatch (jsondiffpatch)
4. https://github.com/chbrown/rfc6902 (rfc6902)
5. https://github.com/kpdecker/jsdiff (diff)
6. https://github.com/Starcounter-Jack/JSON-Patch (fast-json-patch)
7. https://www.npmjs.com/package/just-diff (just-diff)

After having tried them all, the most suitable library to me was: deep-diff

Reason:

1. No external dependencies, thus not having to worry about frequently updating the library.
2. Suitable diff output, this included the type of change, what's the current values, what was the previous one, and the path where the change has been made.

But before we agree on this, we have to make sure that this library is really suitable for us in terms of performance, the output, etc.
Therefore, this issue has been made in order to start a discussion on it. Also, whether we should really go with a ready-made library or make our own.

CC @vinitshahdeo

[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.

[derberg]

I'm always saying don't reinvent the wheel unless over time you see the wheel you are using is not playing its role and its owner doesn't want your help to improve it 😄 (actually it is a first time are articulated it this way 😄 )
So yeah, first use what others spent hours on, and then over time if we see too many limitations we can think of some custom solution.

No external dependencies, thus not having to worry about frequently updating the library.

not a problem from my point of view because we have updating of libraries automated, not a big deal. More important is to make sure the library also can work in a browser so we can integrate it in the future not only in the CLI but also in the UI

I think that while choosing the best library you will face the challenge of "performance vs output quality". The question is - how much is performance really important for us? I think more important is reliable output. So from my perspective, https://github.com/chbrown/rfc6902 looks interesting as it is compliant with standards and looks like actively developed as was released this year.

Just grab this largest AsyncAPI file I've ever seen and see how these diff libraries perform with it.

[aayushmau5]

don't reinvent the wheel unless over time you see the wheel you are using is not playing its role and its owner doesn't want your help to improve it

This just became one of my favorite quotes of all time.

I think more important is reliable output.

You pretty much nailed the point. Right now, instead of worrying about picking up a suitable diffing library, we(@vinitshahdeo, @onbit-syn and I) took a step back, and started thinking about what will the output of our library. We are brainstorming the idea, and will come up something that can be considered suitable, extensible and future-proof.(Will be making an issue about it after some time 😄 ).

So from my perspective, https://github.com/chbrown/rfc6902 looks interesting as it is compliant with standards and looks like actively developed as was released this year.

I will definitely consider this point :)

[magicmatatjahu]

As I see in the Readme of the mentioned tools, they return the path of change and information about the kind of change. Based also on this comment I have an idea to use the XPath or JSONPath and mapping for breaking, non-breaking changes to have relationship between changes and our diff standard.

For example, if someone remove the protocol from one of servers, then from diff tool we should have output that /servers/{serverName}/protocol has changed and based on mapping between our spec and breaking and non-breaking changes, we can extend output that for /servers/{serverName}/protocol is a breaking change or not. Mapping can looks like:

/servers/{serverName}/protocol: {
  'add': 'breaking',
  'remove': 'breaking',
  'update': 'breaking',
}

but for example, if someone add new server, then we can have mapping:

/servers/{serverName}: {
  'add': 'non-breaking',
  'remove': 'breaking',
  'update': 'breaking',
}

etc.

I think that by the mapping our diff tool can be spec-agnostic and easy to extend for the next version of asyncapi. What do you think?

[aayushmau5]

@magicmatatjahu I had some thoughts about how to map our standard into a JSON file, and I came up with something similar.

For example, taking the protocol, we can have

{
  "server" : {
    "protocol" : {
       "add": "non-breaking",
       "remove": "breaking",
       "update": "breaking"
     }
  }
}

But I like your approach better because you have basically flattened the nesting, which would be faster + easier to find, and having JSONpath is certainly a plus point. I will look into how we can implement it(like bypassing the {serverName} and stuff). 👍

Thanks :)

[magicmatatjahu]

We can also use the normal JSON as in your suggestion - we should choose which is better and easier to maintanance :)

[derberg]

I think that no matter what format you choose, it is a good decision to have this mapping approach, for first version any decision will be good imho