finalize all use of data types in named parameters

[sichvoge]

In RC1, a named parameter such as header or query parameter is defined as a "properties declaration". That might impose restrictions, for example, between query parameters. We need to finalize what the value of named parameters are in relation with types.

[usarid]

Replace the entire contents of the section titled "The Query String as a Whole" with the following, after making it consistent, if necessary, with our new terminology for describing YAML nodes, and after making the sentence containing "must be derived from" consistent with the way we discuss type expressions and extending types.

Note that this example is the same as in #319.

---

The queryString property is used to specify the query string as a whole, rather than as name-value pairs. Its value is either the name of a type or an inline type declaration. The type must be derived from a scalar type or from a map type.

If the type is derived from a scalar type, the query string as a whole MUST be described by the type.

If the type is derived from a map type, processors MUST regard the query string as a URL-encoded serialization of an instance of this map type; that is, the query string must be of the form "parameter1=value1&parameter2=value2&..." where "parameter1", "parameter2", etc. correspond to the keys in the map type, and the values to the corresponding value specifications in the map type. If a value in the map type is an array type, processors MUST interpret this as allowing multiple instances of that query parameter in the query string. In such a case, the underlying type of the array -- namely, the type of the elements of the array -- MUST be applied as the type of the value of instances of this query parameter.

In the following example, union types and extending from multiple types are used to constrain the query parameters to specific alternatives:

#%RAML 1.0
title: Illustrate query parameter variations
types:
  lat-long: # lat & long required; mutually exclusive with location
    properties:
      lat: number
      long: number
  loc: # location required; mutually exclusive with lat & long
    properties:
      location:
  paging: # each is optional, not exclusive with anything
    properties:
      start?: number
      page-size?: number
/locations:
  get:
    queryString:
      type: [paging,  lat-long | loc ]
      examples:
        first:
          content:
            start: 2
            lat: 12
            long: 13
        second:
          content:
            start: 2
            page-size: 20
            location: 1,2
        third:  # not valid
          content:
            lat: 12
            location: 2
          strict: false # because it's not valid

[usarid]

I don't know that the other section on named parameters (URI parameters, base URI parameters, and headers) need any changes.

[sichvoge]

Don't think so since most clearly state that the value of each is equal to a properties declaration. If we find something else, we can easily create a separated issue and clean that.