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

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

petrochenko-pavel-a / raml-js-parser2-issues

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