Why write a new JSON Reference library

[whitlockjc]

I'm not against healthy competition, but as someone who advocates for a better OpenAPI community, I have to wonder why json-refs wasn't used instead of writing yet another JSON Reference resolver. I realize that by me being the author of json-refs it might come of as me being upset you didn't use my thing, but that isn't it. As an advocate for a better, stronger OpenAPI community, seeing yet another * worries me because it causes fragmentation. Instead of a community effort to provide a best of breed library, we end up with implementations that heavily overlap. It's confusing and no one wins.

[whitlockjc]

Please know, this is a conversation starter and not a criticism. Everyone is entitled to create their own stuff. But sometimes it happens due to a lack of knowledge, others it's because of some flaw in what's available (something I'm also interested in, I'd love to make json-refs better). Regardless the reason, I think it's a good conversation to have as an OpenAPI community member.

[marbemac]

Hi @whitlockjc, the answer is (I think) pretty simple. I wrote the original code for this json reference implementation way back when it was just me at Stoplight. Wether or not that was technically before json-refs was created, I'm not sure (and honestly, probably not, json-refs looks like it has been around for a while), but I didn't know about json-refs at the time (in fact, this is the first I'm learning of it, looks quite robust!). In 2018 the code was extracted out of our private internals into the standalone package that you see here.

I'm not opposed to consolidating to json-refs, but right now we don't have the bandwidth to a) evaluate json-refs to make sure that it has everything we need and b) actually update all of our code bases to use json-refs, and then test them with some of our more exotic / tricky use cases.

Happy to leave this open though, as a reminder to revisit asap, whatcha think?

[whitlockjc]

Fair enough, and thanks for taking the time. No need to keep it open I guess, I don't have access to your internal code to help with the refactoring to see if it's even feasible. Ultimately, I just wanted to help us all save time and effort solving the same problem. If I can help with anything, let me know.

[knji]

Just ran into this conversation while looking forward tool to resolve external references in our API specs. @whitlockjc, I suspect that if json-refs is listed in OpenAPI tools it will be more visible within the realm of API dereferencing. I will be experimenting with this along with other API validated tools but I found your tool by accident.

[whitlockjc]

@knji Maybe that's what I'll do but since JSON References are not an OpenAPI feature, or at least not specific to OpenAPI, it didn't make sense to me to register it there.

[philsturgeon]

Thankfully we've managed to replace our requirements for this library with another. We ended up going with https://github.com/APIDevTools/json-schema-ref-parser as it matched our specific needs the closest.

Thanks for pushing tooling vendors to focus on collaboration @whitlockjc! It's a trend I hope we can continue at Stoplight and all around the API Ecosystem. :D

[JounQin]

So there are three solutions in this single conversation...

@philsturgeon Did you mean https://github.com/APIDevTools/json-schema-ref-parser is the successor to replace https://github.com/stoplightio/json-ref-resolver?

It is really confusing to choose between them. 🤣

[philsturgeon]

Yes, this library is deprecated and that library is the one you should use. I tried to make that as clear as possible with the description and links on the repo.