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