Clarify that libraries may be used in any type of fragment

[jstoiko]

The spec says:

Any number of libraries can be applied by using the OPTIONAL uses node ONLY at the root of a master RAML or RAML fragment file.

(see "Applying Librairies")

However the uses property is only listed under the "Library" fragment list of properties.

Proposed changes

• in the "Typed Fragments" section, underneath the fragment identifiers table, add a table of allowed nodes containing uses?, e.g. In addition to any nodes allowed in any of the Relevant RAML Specification Section above, the following OPTIONAL nodes are allowed:
• add typed before each occurrence of fragment file (as originally suggested in #357)
• remove the word master to avoid confusion, i.e. root of a RAML or RAML fragment file (the term "master" is only used in the context of Overlays & Extensions)
• remove the unnecessary word "ONLY", i.e. Any number of libraries can be applied by using the OPTIONAL uses node at the root of a RAML or RAML typed fragment file

[postatum]

@jstoiko If you suggest that uses: can be used in all the typed fragments then I don't think it's true, according to current spec.

In the Typed Fragment section it says:

If a file begins with a RAML fragment identifier line, and the fragment identifier is not Library, Overlay, or Extension, the contents of the file after removal of the RAML fragment identifier line MUST be valid structurally according to the relevant RAML specification.

Thus it seems like uses: can only be used in Library, Overlay and Extention.

---

For example, if we define a DataType fragment like so:

#%RAML 1.0 DataType
uses:
  lib: somelib.raml
properties:
  first : string
  second: string

and use it here

...
types:
  User: !include datatype.raml
...

and then replace the !include with its content, it would become an invalid RAML Type declaration.

...
types:
  User:
    uses:
      lib: somelib.raml
    properties:
      first : string
      second: string
...

[jstoiko]

Very good point. That part needs to be corrected as well. Something like:

If a file begins with a RAML fragment identifier line, and the fragment identifier is not Library, Overlay, or Extension, the contents of the file after removal of the RAML fragment identifier line and any uses node MUST be valid structurally according to the relevant RAML specification.