Forum Discussion

Agh42's avatar
Agh42
New Member
5 years ago

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 extern...
HKosova's avatar
HKosova
SmartBear Alumni (Retired)
5 years ago

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.