Map types in the "type" and "is" attribute have an ambiguous meaning


#1

The spec states that:

The value of the type attribute MUST be either a) …, or b) one and only one resource type definition map.

and

The value of the is attribute MUST be an array of any number of elements, each of which MUST be a) …, or b) one or more trait definition maps.

So far, so good. If we come across a map in a type or is attributes, then they will be a type definition and a trait definitions.

But the spec also says:

To pass parameter values to resource types and traits, use a map when declaring the resource type or trait to be used.

Now we can’t easily tell whether a map in a type or is attribute is a resource type/trait name with parameters or a definition.

We can try to guess. types/traits names with arguments will consist of an object with a single property with a value that is a map, and the single property must exist in the top-level resouceTypes/traits attributes. But maybe there is a typo, in which case we’ll end up parsing the definition as a resource type or trait, maybe generating an error, maybe not.


#2

Good find, @elevy! This could definitely be clearer.

Can I suggest opening an issue for this over at https://github.com/raml-org/raml-spec? I’m not a part of the workgroup, but I believe they’ll be putting some fuel on the fire to clean up 0.8 and work towards RAML 1.0 quite soon, so hopefully they’ll address this as part of that effort.


#3

Already done: https://github.com/raml-org/raml-spec/issues/63