Make handling circular references configurable

[whitlockjc]

We need to make it where a configuration option can dictate whether circular references are replaced with its original definition or {}.

[brettz9]

Would it be equally difficult to support resolving into genuinely cyclic (non-JSON) objects as with your prior support of depth?

(It appears my validator (Ajv) can support circular schemas, so building cyclic objects might work out nicely in the absence of depth (or even preferable to it in some cases, by its avoiding memory problems and uncertainty as far as the depth one would require).)

[whitlockjc]

Well, if your validator can resolve relative references it should also be able to resolve the circular reference for validation. ;) In all seriousness, I could end up with bringing back depth support but I do remember it being a pain...although with the new API it could be trivial.

[cen1]

Any ETA on this? It breaks a major tool (swagger-ui) and has been open for over a year.

[whitlockjc]

How is swagger-ui impacted? They use swagger-js which has its own resolver and does not use json-refs. PRs welcome.

[cen1]

This issue was referenced in swagger-api/swagger-editor#1005 perhaps incorrectly.

[whitlockjc]

Ah, swagger-editor. That's different than swagger-ui. I'm currently rewriting the resolver and once it's done, this will be high on the list. I just don't have as much time on these projects these days since I don't do them as part of my day job. I'm working on it.

[whitlockjc]

What if json-refs, and thus sway and all tools using them, stopped trying to circumvent (remove/replace) circulars and instead resolved references as-is?

[whitlockjc]

The reason circulars were originally removed/replaced was due to tooling I was building around not supporting circular documents. This wasn't fair. I do think I could make it configurable but my worry is that no one will ever be completely satisfied.

[whitlockjc]

options.allowCircular was added. If you set it to true, circular references will be resolved allowing the caller to do whatever they want with the circular documents. There is no good way to add depth or another more configurable option without completely decimating performance so I think this is a good middle ground until we can come up with something better, if people still want something else now that we have this new feature.