Ambiguity on parser requirements for HTTP resources


#1

In the current version of the spec, it says:

If a relative path is used for the included file, the path is interpreted relative to the location of the original (including) file. If the original file is fetched as an HTTP resource, the included file SHOULD be fetched over HTTP.

In the following example, because the original (including) file is located at http://example-domain.org/api/example.raml, the properties.raml file should be fetched from http://example-domain.org/api/properties.raml.

If the included file has one of the following media types:

application/raml+yaml
text/yaml
text/x-yaml
application/yaml
application/x-yaml
or a .raml or .yml or .yaml extension, RAML parsers MUST parse the content the file as RAML content and append the parsed structures to the RAML document’s node.

There’s an ambiguity here in whether or not the parser is required to fetch the resource via HTTP. The text seems to suggest that it should, but does not actually require it; for instance, media types can be discovered from headers in an HTTP response, but can also be discovered via file and/or the database from shared-mime-info.

The only thing clear here is where relative metadata is required to live when the original is from an HTTP endpoint. It should probably be clear whose responsibility it is to fetch included documents – the parser or the user.