Remove sequences and composition in RAML 1.0 for global definitions like traits and resource types

[VasiliyLysokobylko]

RAML 1.0 is the first major release, and we want to be very close to one of our missions to introduce simple ways to share and collaborate pieces of your API design. In the past, we introduced concepts to define reusable definitions globally or in separated files, which could be easily included on or composed with other definitions. An example of such may be the following:

traits.raml

# external traits definition
pagination:
  queryParameters:
    offset:
      description: Skip over a number of elements by specifying an offset value for the query
      type: integer
      example: 20
      default: 0
    limit:
      description: Limit the number of elements on the response
      type: integer
      example: 80
secondTrait:
   description: just a second trait

api.raml

#%RAML 0.8
title: Pagination API

traits: 
  - !include traits.raml # composing with includes from traits.raml
  - otherTrait: # explicit trait definition
      description: just another trait

RAML 1.0 takes the concepts of reusability or modularization one step further with introducing fragments and libraries. Both add significant value to the core concepts already mentioned and make some of the previous mechanism introduced above obsolete; especially composition. The above example can be also perfectly expressed using libraries.

traits.raml

#%RAML 1.0 Library

# external library

traits:
  pagination:
    queryParameters:
      offset:
        description: Skip over a number of elements by specifying an offset value for the query
        type: integer
        example: 20
        default: 0
      limit:
        description: Limit the number of elements on the response
        type: integer
        example: 80
  secondTrait:
     description: just a second trait

api.raml

#%RAML 1.0
title: Pagination API

uses:
  externalTraits: traits.raml
traits:
  otherTrait:
    description: just another trait

Using libraries, and also fragments, are coming with a couple of advantages; one being able to give better support for design-time validation and suggestions, and more.

Since we believe that these new mechanism will give significantly more benefits to anyone in the RAML community, we effectively decided to remove the ability to compose any external definitions with global definitions in RAML 1.0 RC2. So in any future version of RAML, you will be not allowed to do the following anymore:

traits: 
  - !include traits.raml # composing with includes from traits.raml
  - otherTrait: # explicit trait definition
      description: just another trait

This change does not only influence the way how you modularize and reuse definitions throughout a RAML API specification, but also the syntax on how to declare them. With 0.8 and 1.0 RC1, the syntax for defining global or external definition was not consistent. To define traits: !include traits.raml your external file had to be a sequence (starting with dash) of traits, whereas you could not use the same file for composition since the requirements for that are a file that contains a map of traits (no dash).

Therefore, with RC2, we also generalize the syntax for global or external definitions to be much more consistent with the rest of the specification. Where you could define sequences in the past (introduced for being able to compose), you will be only allowed to define maps in the future, and not both depending on the context.

# using maps in 1.0 RC2
pagination:
  queryParameters:
    offset:
      description: Skip over a number of elements by specifying an offset value for the query
      type: integer
      example: 20
      default: 0
    limit:
      description: Limit the number of elements on the response
      type: integer
      example: 80
secondTrait:
   description: just a second trait

vs

# using sequences in 0.8 and 1.0 RC1
- pagination:
      queryParameters:
        offset:
          description: Skip over a number of elements by specifying an offset value for the query
          type: integer
          example: 20
          default: 0
        limit:
          description: Limit the number of elements on the response
          type: integer
          example: 80
- secondTrait:
    description: just a second trait

The root-level nodes that will be influenced by this change are traits, resourceTypes, securitySchemes, and schemas from 0.8 and 1.0 RC1.

One will still be able to directly include an external traits definition into the global traits node (traits: !include external.raml) or single traits that is either a trait fragment or just a map of key-value pairs that defines a trait by doing the following:

traits: 
  trait1: !include trait1.raml
  otherTrait: !include otherTrait.raml

In summary, this issue suggests to remove the ability to compose external and global definitions using sequences, as well as changing the value of each root-level node that declares reusable definitions such as trait and resource type, consistently from a sequence to map.

[VasiliyLysokobylko]

https://github.com/raml-org/raml-spec/issues/306