JSON references to external documents - should you still use them?

[Agh42]

I feel hesitant to use external schema references in my OpenAPI documentation - are these here to stay?

I'm wondering because

• There is only a draft that ever mentioned JSON references to external documents via URL and it is expired since March 2013.
• JSON pointers are only allowed locally within a single JSON document (RFC 6901).
• JSON schema defines the "$ref" keyword - but only using local JSON pointers.
•  

Side note: The Swagger specification states that: 

"According to RFC3986, the $ref string value (JSON Reference) should contain a URI, [...]"

This is a misleading statement. RFC3986 ist just the RFC for URI syntax. It does not say anything about the contents of the "$ref" entity.

That's like saying " According to the US food code of 2013, I should have a sandwich in my bag". It does not say that. It just describes how a healthy sandwich should be created. 🙂

[HKosova]

Both local and external $refs are perfectly fine and there are no plans, as far as I know, to disallow external $refs. On the contrary, modularization helps reuse common components across different API definitions.

All of the following $refs are valid:

$ref: '#/components/schemas/Product'
$ref: 'https://api.example.com/schemas/Product.yaml'
$ref: '../common/schemas/Product.json'
$ref: './components.yaml#/Product'

One thing to keep in mind when using external $refs is that the $ref target must be in the format expected in the given context. For example, a schema $ref must point to an OpenAPI Schema Object and not to a "vanilla" JSON Schema. This will change in OpenAPI 3.1 which will support full JSON Schema for schema definitions.