Ambiguity on parser requirements for HTTP resources

[jefferai]

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.

[aldonline]

Hello Jeff,

Thanks for taking the time to report this and for elaborating.

The short answer is that the parser IS responsible for resolving and fetching resources, in the same way that a web browser does this when "importing" files linked to an HTML document ( iframes, script tags, link re=stylesheets, etc ). You are right in that this is not strictly specified and could be corrected. A better explanation should be split into two separate steps:

1. Resolving the absolute URL for included/referenced files. This is done by applying relative URL resolution using the containing document's URL as the base URL. This would "expand" any relative references to absolute references. They will inherit the protocol from the root document ( one of file://, http://, https:// ).
2. Dereferencing and downloading ( aka fetching ) these resources. A well behaved parser MUST dereference these files. The process of dereferencing resources is different for each protocol, but it is well defined for the subset we care about.

Btw - What are you building?

[aldonline]

I think we should also be more clear about the third step. Not sure if this is something we can get into the spec for 0.8 or we will push it for 1.0.

3 . Media Type interpretation. If the request happens via HTTP, then media type is resolved by looking at the media-type header. If the request is via file://, then media type is resolved based on file extension ( TODO: we should define an official list of file extensions to mappings ).

[jefferai]

Hi @aldonline

I totally agree with all three steps and I think together they will remove any ambiguity. I think it's fine pushing to 1.0 if you think 0.8 parsers are all interpreting the 0.8 spec in this way anyways.

We're building a number of applications from scratch and adopting API-Driven Development; after evaluating RAML, API Blueprint and Swagger 2.0 we settled on RAML. Can't go into more detail at the moment, but I can tell you that there are some features of RAML that will make our lives much better especially !include -- which is why I found this ambiguity, as I wanted to ensure it would work the way we expected.

[aldonline]

Hello Jeff, That sounds great! I'd love to have a chat if you have time skype: aldo.bucchi Just ping me if you see me online