Parameter enum of non-strings?


#1

The Named Parameters / enum section of the spec states

(Optional, applicable only for parameters of type string) The enum attribute provides an enumeration of the parameter’s valid values. This MUST be an array. If the enum attribute is defined, API clients and servers MUST verify that a parameter’s value matches a value in the enum array.

Since the enum property is only valid on parameters of type string, it reasons that the enum array can only contain strings.

Which makes the following portion of the Twitter RAML API file rather curious:

  queryParameters:
    include_entities:
      description: The entities node will not be included when set to false.
      enum: 
        - 0
        - 1
        - true
        - false
        - t
        - f

These are not all strings according to YAML. So it the spec wrong or it this RAML file and the tooling that accepts it incorrect?


#2

I just tried what you said, and it works as expected, an enum lets you define any values as possible. i.e.

  queryParameters:
    myparam1:
      enum:
        - true
          false
          1
          0
          t
          f
    myparam2:
      enum: [0,1, t, f, true, false]

worked for me on the API Designer. Whenever I have a question like yours I just go into the Designer and experiment. http://imgur.com/a/EIfII


#3

Hi @elevy you are correct, the tooling is incorrect in accepting these as strings. I would err on the safe side for this and claim that the tooling does the right thing of accepting these, since there is no ambiguity in the context, once they are serialized back to strings.


#4

luix. The whole point is that the API Designer should not allow you to enter those values. Per the 0.8 spec enum is only defined for strings and the values you are entering are not all strings. Therefore the RAML file is invalid. Looks like this will change in RAML 1.0, but as it stands today, that is invalid RAML.