Ability to skip dereferencing inline/internal $ref values #214

[marc0l92]

Add new option to skip the internal references while parsing the document

This pull request fix the issue: https://github.com/APIDevTools/json-schema-ref-parser/issues/214

[philsturgeon]

I'm struggling to see the use case here. So far in #214 it looked like one persons problems were solved with using bundling, then another person was simply using $ref incorrectly (entirely understandable, we've all done it).

Perhaps this is worth merging just for the sake of feature parity with the stoplight tool?

If so, can we document better?

What does skip internal mean? If it means "only replace $ref for external files but keep $ref for internal files" that kinda sounds like bundling? Maybe I've been away from my computer for too long or something. Please help me understand what we're trying to do.

[marc0l92]

Hello @philsturgeon, thanks for reviewing this pull request.

You are right to be confused about this issue because it makes the bundling working in a different way, but let me explain you a bit of background.

In my company we created several OpenAPI files using the references in a different way than the official one and we were using a different library bundle them. The previous library is not supported anymore, so I decided to modify our project to this library to bundle the files because it looks well done and maintained.

The references that this library expect are structured like this:

The reference that I'm using in my company are like this:

Both approaches have advantages and disadvantages. For example, the second approach allows you to create links only one layer deep and centralize the versions in a single file (the root). In this way, if a new version of a shared object is released, you need to change it in only one place. In this example, if you want to migrate to obj3.v4 you need to change it only once.

Another advantage is that you can share parts of an object between apis. In this example, if two apis wants to share the same obj1 but a different implementation of obj3 they can do it without duplicating the file obj1.

This can be useful is some situations but annoying in others. If you look at obj1.v1.json alone you are not able to understand its content until you put it inside a complete api.

Anyway, my goal is not to convince you that this alternative method of linking is a valid one, but explain why the option in this pull request is needed.

My team decided to use the second linking approach long time ago and, if possible, I would like to keep it in this way using this library to do the bundling.

How do you suggest me to document this option in github pages? do you want to rename the option value?

Thanks, Marco

[philsturgeon]

Have you seen this? https://apisyouwonthate.com/blog/json-schema-bundling-finally-formalised/

With $id and new tooling that supports $id in $ref, there is no reason for anyone to work on custom solutions or awkward hacks anymore. We could all just use $id.

This codebase has some plans to support the new hotness in https://github.com/APIDevTools/json-schema-ref-parser/issues/145, which really is a rewrite in the form of https://github.com/APIDevTools/json-schema-reader, but that rewrite has been paused due to life kicking everyone in the face. Experimentation and PRs welcome.

[marc0l92]

Link updated: https://json-schema.org/blog/posts/bundling-json-schema-compound-documents