Validating query parameters in RAML

Question

I need to create an API that has four possible HTTP query parameters. Either parameter one or parameter two is required. The others are optional. From the official RAML version 1.0 specification on Github, I found an almost exact scenario in the RAML queryString example.

I loaded it into Mulesoft Design Center to test it out. The RAML produces no errors in Design Center, and everything looks okay. According to the first example in the RAML, the following URL should produce a success (200 OK):

GET https://(mocking URL)/locations?start=2&lat=12&long=13

When I send it via Postman, it reaches the mocking service, but I get the following error:

{
    "code": "REQUEST_VALIDATION_ERROR",
    "message": "Error validating query string: expected type: JSONObject, found: Null"
}

I'm not sure if this is a Design Center limitation or if there's something off in my URL. Does anyone know what I'm doing wrong?

Here's the RAML sample from the official spec:

#%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:
          value:
            start: 2
            lat: 12
            long: 13
        second:
          value:
            start: 2
            page-size: 20
            location: 1,2
        third:  # not valid
          value:
            lat: 12
            location: 2
          strict: false # because it's not valid

@George Thanks for the response. Is this bug documented somewhere? — Tony

aled aled · Accepted Answer · 2020-08-08T13:43:31

The RAML specification explicitly does not define validation for object types:

RAML does not define validation when a query parameter declaration specifies any of the following types for the value of the query parameter: an object type, a union of non-scalar types, or an array type if the underlying type of the array is an object type or union of non-scalar types. Processors MAY default to treating the format of the query parameter value as JSON in applying the type to instances of that query parameter, or they MAY allow other treatments based on annotations.

Even if the Mocking Service implements the validation eventually, it might be better to use simple types for query parameters, like strings and numbers. It makes sense because usually query parameters are just used that way.

Validating query parameters in RAML

2 Answers