Request body can have 1 of 2 different XML schemas - include schema as doc?


I have to use RAML to describe an API for which 1 request can conform to 2 different XML schemas.

I obviously can’t put both schemas into 1 post: heading.

What is the appropriate way? Do I need to provide 2 post: methods, one for each schema?

Or is the best I can do to somehow embed the alternative schemas in markdown docs?

If so, how?


So, if I do this using 2 post: objects the same object appears twice in the RAML2HTML output, which is no use.

I found a supposed way to make 2 schemas into one:

…but his means more work due to namespaces etc…

Anyone found an elegant solution here?


Well, really the only right way to do this is to use custom media types, one for each document. That is you would have something like: application/ and application/ to specify different Accept or Content-Type headers. Then your RAML would have something like:

schema: xsd1
schema: xsd2

If it is a POST/PUT/PATCH with a body being sent in… same thing. Though, to be honest this sort of two or more different document types should only be for responses. I would suggest different resources for sending in two or more different body types on a POST/PUT/PATCH request.

In the above definition… the API consumer would pass in the Accept header one or the other media type to indicate which they want back.


Thanks @Kevin_Duffey for your kind response - this sounds logical. We’d have to make our users use the headers, but I guess that’s the price of clarity.