Is this doc still relevant?

[LappleApple]

https://github.com/zalando/api-first-hand/blob/master/docs/REFERENCES.md

Asking because the main README has this:

If not, we can delete it.

[slavaschmidt]

The REFERENCES is in-depth explanation how we work with json references in the plugin's source code. This is supposed to be useful for plugin developers as opposed to the plugin uses, for which is the section in the README

[LappleApple]

Thanks, @slavaschmidt! This sentence is a little confusing: "A $ref element of the specification is allowed to contain a name of file as its part." As its part of what, exactly? And "a name of file" means ... can we be a bit more specific?

[LappleApple]

Also this sentence: "It is also possible to reference a definition in one specification from another specification." [rewrite as?] => "You can reference a definition in one specification across other specifications."

[slavaschmidt]

This sentence is a little confusing: "A $ref element of the specification is allowed to contain a name of file as its part." As its part of what, exactly? And "a name of file" means ... can we be a bit more specific?

It basically means, you can use filename to reference part of another specification.

[LappleApple]

Does this make sense to you, @slavaschmidt?

You can use a filename to reference part of another specification with the $ref element. You can split a single specification into multiple files (as shown in cross_spec_references.yaml). You can also reference a definition in one specification across other specifications.

[slavaschmidt]

Totally. For example one can create domain_model.yaml and then reference it from any other API specification

[LappleApple]

Awesome, thank you @slavaschmidt!