Ask a Question

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

New Member

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

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. 🙂


SmartBear Alumni (Retired)

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: ''
$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.

Helen Kosova
SmartBear Documentation Team Lead
Did my reply answer your question? Give Kudos or Accept it as a Solution to help others. ⬇️⬇️⬇️
Showing results for 
Search instead for 
Did you mean: