Media type hints & overrides

[awwright]

Occasionally it's been asked how $ref should work when targeting an arbitrary location not known to be a JSON Schema or JSON, or when found in an arbitrary location not known to be a JSON Schema. Should you be able to point to an arbitrary document?

This question comes up because sometimes it's useful to host a document at places where you can't completely configure the media type (specified in HTTP using the Content-Type header).

In Web architecture, the target document gets to determine its own media type, not the source of the link. This provides important security guarantees, so that even if a document appears to be valid in multiple interpretations (a "polyglot document"), only the interpretation intended by the origin server will be used, and not a potentially malicious one.

The other benefit is that the server can return a variety of media types. A server might return a YAML document instead, and the client can still make use of that, rather than producing a syntax error as it tries to parse the document as JSON. The server may even return different media types depending on what the client supports. When the source of the link assumes the target is JSON, these features are not possible.

Links can define a hint "type" attribute, which may be used for optimization purposes, or to request a specific media type when multiple are available.

If there are cases where this is insufficient, it may be possible to "override" the media type specified by the target document, but this has the noted disadvantages.

Also note that this issue really only concerns use in HTTP (and compatible protocols that use media types... email...) and doesn't concern local filesystem access. Or rather, if you have local filesystem access, then you're also the one specifying the media type of the files on that filesystem. (That is: This issue is only relevant when there is a boundary that must be crossed: when the target is hosted by a different party than the source.)

Given this, I'm not sure this requires any action. Or I'd suggest describing $ref as a link. Then all you have to do is say "$ref forms an embedded link to the target document".

[jdesrosiers]

I feel like overriding the media type declared by the Content-Type response header would be a violation of the HTTP specification. I'm not sure that the spec actually says that applications can't ignore Content-Type, but it's at least understood that they shouldn't do that even if it's just for security reasons. In the JRef proposal, I spell out that implementations MUST respect the declared media type, but I'm not sure a spec really needs to say that. It should be implied just by supporting HTTP requests/responses.

However, it's worth noting that most JSON Schema implementations and other $ref tooling that use HTTP requests ignore Content-Type and assume the media type is what they expect. I think that's at least a bad security practice and possibly a violation of the HTTP spec. In any case, any spec that comes out of this effort should not have language that explicitly allows or recommends ignoring media types.

What could make sense is to add support for some feature that sets an Accept header on the request to signal to the server what media type(s) they need. For example, a property in an AsyncAPI document that expects an XML Schema can use that feature to specifically request an XML Schema media type response. The implementation would still have to fail if the response media type was not an XML Schema rather than trying to parse whatever they get.