Clarify "uses" syntax

[hwellmann]

It is not quite clear whether includes, libraries, overlays and extensions all support the same syntax for absolute or relative paths or URIs that are defined for includes.

There is an explicit cross-reference from overlays and extensions to includes:

An overlay or extension document MUST contain a root-level extends node whose value MUST be the location of a valid RAML API definition or another overlay or extension; the location specification is an absolute or relative path, or a URL, equivalent to an !include tag argument.

No such reference exists for libraries. Thus it is not clear how to locate library resources in the following example:

uses:
  foo: foo.raml
  bar: /bar.raml
  baz: http://acme.com/raml/baz.raml

[machaval]

In my opinion having libraries being resolved relative to the root raml makes them not portable. This means that if they are open by any editor it is going to be broken. They need to be standalone.

[sichvoge]

AFAIK, the syntax is exactly the same as defined for !include (see table in this section).

I agree that we need to clarify that inside the specification!

IMHO, referring to @machaval comment, I very much dislike the way how we describe "absolute path". In fact, I don't know if we should even have that. I am seeing the exact same problems with resolving everything relative to a "root RAML" file. What does that actually mean and what happens when a library uses another library using an absolute path? As Mariano said, libraries or any fragments should be valid standalone in my opinion.

[petrochenko-pavel-a]

Completely agree with @sichvoge in this case

[usarid]

@sichvoge @machaval @petrochenko-pavel-a how do you propose that absolute paths be handled within fragments? The only options I see are to interpret them as 1) relative to the root RAML that ends up using them or 2) relative to the fragment location or 3) to disallow them. It feels like 3) is a breaking spec change so not acceptable for 1.0. As for 1), that's consistent with !includes but makes fragments fragile with respect to portability and makes validation of fragments on their own impossible (so we'd pretty much recommend that fragment authors simply don't use absolute paths that aren't a full URL). As for 2), it forces portability but is inconsistent with !includes, and it also in some cases breaks specs that bundle their own fragments and use absolute paths to cross link those fragments. So I'd go for 1), and rely on tooling and maybe a caution in the spec to warn developers about the consequences of using absolute paths.

[sichvoge]

Thanks @usarid.

What, in your mind, should be defined as the root RAML? Is that always the one that gets parsed or some file that's being defined somewhere to be the root? That is what I don't understand in your statement.

Maybe to parse a fragment, you always have to also point to a "root" file. Something like, parseFragment(fragment,rootRaml)? But then we probably should change wording inside the spec that a fragment needs to be valid in context of the root RAML file.

The above is probably very contra-productive especially for libraries, though.

And again, absolute paths are a breaker for fragments and I don't know if a simple warning in the spec will solve this. It's a pity to have it.

BTW, that behaviour should be consistent across uses and includes.

[petrochenko-pavel-a]

What, in your mind, should be defined as the root RAML?

Root RAML file is the the file which was initially requested to be parsed.

some file that's being defined somewhere to be the root?

The problem with this approach is that if we follow it, it becomes impossible to validate fragment on it's own.

As for me it is conceptually impossible to make absolute paths consistent (those which are not full urls) without introducing such term as a RAML project (and of course the mechanism to find project location form location of the fragment) into the spec)