[SOLVED] How to correctly define Accept-Encoding: gzip header in RAML?

How to correctly define Accept-Encoding: gzip header in RAML?

I need to describe a REST API that always returns gzipped response in terms of RAML 1.0 specification.

The API RAML specification must indicate that the API requires the header Accept-Encoding be always sent in the request. Furthermore, the Accept-Encoding value must be either '*' or 'gzip' or have 'gzip' among other acceptable encodings specified e.g. 'compress, gzip' or 'compress;q=0.5, gzip;q=1.0'.

As a first iteration, I've defined the mandatory header like this:

headers:    
  Accept-Encoding:
    type: string
    required: true
    example: 'gzip'

But this, of course, does not indicate that only 'gzip' encoding is supported by the API.
Pls help with defining more detail RAML specification for the 'Accept-Encoding' header.

Solution

RAML doesn't has the expressiveness to validate the values with specific rules. You can set a pattern with a regular expression to restrict the value:

headers:    
  Accept-Encoding:
    type: string
    required: true
    example: 'gzip'
    pattern: ^(\*|((.+,)?\s*gzip\s*((,|;).+)?))$

This pattern doesn't guarantee the value will be a valid list but it verifies that it is either only * or gzip standalone or surrounded in either side by commas. You could improve the regular expression to ensure that both sides are comma separated lists, however that kind of validation is outside of what is expected of RAML and belongs in the application code.