Proposal: support type-specification on ?merge tags? (e.g. like {traitName: {<<!string tagName>>}})

[sammy-hughes]

I propose that RAML specify behavior for ?merge-tags?, with traits and resource types, allowing a type to be specified. Generally it can safely be assumed to be a string, but there are two edge cases that I believe are meaningful.

The examples which follow will reference a type, identityProvider, defined as follows:

types:
  identityProvider:
    type: string
    enum:
    - oldIdentity
    - newIdentity

For the examples of syntax, the context would be a trait definition such as follows:

traits:
  secured:
    queryParameters:
      <<provider>>:
        description: A valid <<provider>> token is required

I found a broadly-compatible, expressive, and quite clear version of that definition to prepend the variable name with a YAML tag, rendering it<<!identityProvider provider>>. Another form that would work just as well would be <<provider: identityProvider>>. The former keeps it simple and easily lexible (lexable?), while the latter would appear to allow, and probably should allow, inline type declarations. Unfortunately, the latter form introduces an ambiguity in lexing, where the interpretation is dependent on the specific pattern of the value.

While I suggested an example of the former kind in the subject line, the specific syntax is immaterial. The essence of this proposal is rather that there be a standard syntax, which assorted tooling maintainers can then support in a consistent manner.

The two ares where this is meaningful is, A, when the value should be restricted beyond "any string", and B, when the value is to be interpreted as being a type-parameter.

Case A is demonstrated above, where provider is expected to be a value only from a permissible set, but it may also be a number, a hexadecimal value, a specific UUID, or even some kind of structured value.

Case B would be when a type parameter is expected, such as follows:

traits:
  typedTree:
    left: <<!type treeType>>
    right: <<!type treeType>>

Both cases can be lexed according to the needs of specific applications using presently standardized syntax, but this proposal offers a way for the RAML spec to be more expressive, in a way that translates across individual tooling providers.