search

raml-org / raml-spec

RAML Specification
http://raml.org
3.87k stars 857 forks source link

Clarify `uses` node in typed fragments #741

Closed jstoiko closed 3 years ago

jstoiko commented 4 years ago

Closes #718

BlockLucas commented 4 years ago

Hi!

Typed fragments didn't specify the usage of “uses” facet, hence the explanation that they MUST be valid according to the relevant RAML specification forbids that. For us is not a PATCH change as a NamedExample with "uses" as defined in 1.0.1 would be invalid for 1.0

jstoiko commented 4 years ago

@BlockLucas: I think you're putting the finger on the issue that led us to making this clarification (and other clarifications we're including in 1.0.1). Libraries were always meant to be used within any kind of typed fragment. This is what the RAML 1.0 Spec currently 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. (...) For example, a RAML type fragment file that uses a library of remote types can import one of those types by referring to it. The remote type is included as if it were defined locally within the RAML type fragment file.

What we did is we went back to the original discussions that took place prior to the release of the RAML 1.0 spec to understand what the original intent was. And in this case it was pretty obvious that the intent has always been to have libraries be used in any RAML file, whether a RAML API or RAML typed fragment definition. The fact that the "Typed Fragments" section does not have the uses: node facet defined currently is an obvious mistake. Fixing this mistake by adding this table doesn't change the fact that these two sentences above were there in the first place.