raml-spec
raml-spec copied to clipboard
Specification is not clear about how to use libraries
When applying libraries some people get confused and think they have to use the include keyword.
See these questions on stack overflow:
http://stackoverflow.com/questions/42427263/mulesoft-error-ramlparser-loadpath-loadapi-content-object-object-no-such/42439035
http://stackoverflow.com/questions/42397718/raml-include-strange-behavior/42398663
Although examples are correct I could not find anywhere in the specification doc that states clearly that the "include" keyword should not be used when applying libraries ("uses:")
I completely agree with you. I would probably add a sentence to the third paragraph inside the Applying Libraries chapter. Something like:
OLD:
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. The value of the uses node is a map of key-value pairs. The keys are treated as library names or namespaces, and the value MUST be the location of a RAML library file, usually an external RAML library fragment document.
NEW:
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. The value of the uses node is a map of key-value pairs. The keys are treated as library names or namespaces, and the value MUST be the location of a RAML library file, usually an external RAML library fragment document. Other than including a fragment file, the location is defined without using the
!include
tag.