Description
File Structure section says
The OAS representation of the API is made of a single file. However, parts of the definitions can be split into separate files, at the discretion of the user. This is applicable for $ref fields in the specification as follows from the JSON Schema definitions.
However, the cited http://json-schema.org/ page does not define $ref
-- one must dig to find a mention of it or here but even those do not define what $ref
is or can express.
I think a better link might be JSON Reference and JSON Pointer.
This would help improve #636 for example making clearer that examples could be outside the spec file in linked (relative or http://) resources. Both links are necessary because the former is not clear about links outside of the document that contains the JSON Reference.