cancel
Showing results for 
Search instead for 
Did you mean: 

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. :-)

 

1 REPLY 1
Highlighted
Moderator

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

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.


Helen Kosova
SmartBear Technical Writer
________________________

 Join SmartBear Connect next April in Boston to meet with software development, API and testing experts from around the world! Get your ticket today!