Multiple json schema for response


#1

Is there a way to specify multiple response schemas in RAML. Example:

/users/1.json -> returns {id: 1, name: 'John Smith'}
/users/1.json?full=true -> returns {id: 1, first_name: 'John', last_name: 'Smith', email: 'johnsmith@example.com'}

Idea is that response schema can possibly be different based on supplied request parameters. And right now I don’t see a way to specify multiple json schemas for single response.

Thanks


#2

Hi @romanoff, thanks for the comment. How would you relate an example to a specific request? In your case you would send back that specific json only if you specify full=true


#3

That’s correct. Basically, data can be represented with different json templates and template is selected based on parameter. Other option could be to use some “type” parameter. So, type=default or type=show or type=full. But the idea is that you have different json schema based on request parameter.


#4

Currently, you COULD specify different response types based on your requirements. I would not stick to it, but that could be something you can do if you really want.

application/json:
    example:
application/json+defaultype:
    example:
application/json+fulltype:
    example:

As I said - that is a workaround as RAML don’t support multiple response types. application/json can be still used for the actual response type and the other just for testing.


#5

Thanks. This will work


#6

I’d argue that what you are requesting is filtering of a single media type. Specifying full or some other value via a query parameter would be a subset of the one mime type would it not?

Even so, it would be great (assuming what I said is correct) to specify subsets of responses based on query parameters as well as include examples for each query parameter filter, to allow for more verbose documentation/examples.


#7

@romanoff, @justjacksonn - can you do me a favour (one of you) and create a reporting on the spec github page https://github.com/raml-org/raml-spec - so that your request can be tracked. Thanks


#8

https://github.com/raml-org/raml-spec/issues/137

Is that a decent enough explanation? If not, please edit/append to make sure we have it documented what is needed. Hopefully this can get in to the 1.0 spec… it is a much needed item.