Agh42
5 years agoNew 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. :-)