Remove support for any inline definition (implicit or explicit) for traits, resource types, and security schemes

[sichvoge]

Original Discussion: #302

In RAML 0.8 and 1.0 RC1 you were able to define inline (anonymous) traits, resource types, and security schemes either explicitly or implicitly using !include. This syntax is a shortcut that promotes a bad design practice, as you will not be able to reuse the trait in your api unless you include the same file more than once which does not look very DRY. Also the feature is crippled as you can inline only certain types of traits or resource types, those that do not use parameters.

As there might be some advantages, they are very small compared with the complexity and bad design you introduce into the spec and your API design. Therefore, the suggestion is to remove the ability to define inline definitions (implicit or explicit) for traits, resource types, and security schemes.

So the following are examples that are not valid in RAML 1.0 RC2 anymore:

/resource:
  get:
    is:
      - !include trait1.raml
      - !include trait2.raml

/users:
  type: !include types/collectionBase.raml

/resource:
  get:
    is:
      - queryParameters:
          query1:
      - queryParameters:
          query2:

If one has, for example, a resource type defined in an external fragment file; it is recommended to use the global definition to include it into your RAML definition.

resourceTypes:
  baseCollection: !include types/collectionBase.raml
/users:
  type: baseCollection

This change is restricted only to traits, resource types, and security schemes; and you will still be able to use that mechanism for any other such as type.

/users:
  get:
    responses:
      200:
        body:
          type: !include users.json

[usarid]

I believe the best reason to do this is for simplicity in fulfilling their purpose. Specifically, traits and resource types are meant to encourage consistency across multiple places in an API spec and across multiple API specs. That means they should be defined somewhere higher than than the scope of a single location in an API spec, in a global declaration and/or in an external file, and then applied in multiple places. Inline definitions at the place of application cannot fulfill that purpose because they're not reusable, except in the special case where the inline definition is itself an !include from an external file that could be applied in multiple places. But even that special case does not allow the application of parameters (which are always applied using the name of the trait/resource type), and it comes at the cost of complexity, because it mandates allowing non-!included inline definitions (because !includes are equivalent to inlining their contents). Instead, it's much simpler to restrict traits and resource types to always have names, via global declarations (or libraries).

Accepted.