Body property in spec is incompletely described


#1

The spec, in the Body section, states:

A method’s body is defined in the body property as a hashmap, in which
the key MUST be a valid media type.

The Responses section state:

Each response MAY contain a body property, which conforms to the same structure as request body properties (see Body).

Note that neither section makes any reference to a default media type.

So from reason this, we’d assume that the keys of body property hashmap MUST be valid media types.

Alas, Mulesoft’s sample RAML APIs, such as Twitter’s, show things like:

  responses:
    200:
      body:
        schema: ...
        example: ...

Presumably this is because the mediaType root property has been, so that is the expected request and response body media type.

The Default Media Type section says

The media types returned by API responses, and expected from API requests that accept a body, MAY be defaulted by specifying the mediaType property.

But nowhere does the spec discuss the fact that the body property instead of being keyed by media types, can contain the properties associated with the default mediate type. In fact, only a single example in the spec uses this technique, in the Parameters section, and its not discussed.

Aside form the lack of description in the spec, this option means that you must look at the keys of the body property and determine whether they are mediate types and if and only if they are not, assume the user mean to use the default media type and that the keys are the body properties.


#2

It looks like is exactly as you supposed… for instance

#%RAML 0.8
title: Test API
mediaType: application/json
/service1:
  get:
    description: description of the service1
    responses:
      200:
        body:
          example: |
           {
              "glossary": {
                "title": "example glossary"
              }
            }
/service2:
  get:
    description: description of the service2
    responses:
      200:
        body:
          application/xml:
            example: |
              <note>
                <to>Tove</to>
                <from>Jani</from>
                <heading>Reminder</heading>
                <body>Don't forget me this weekend!</body>
              </note>

The service1 response will asume its json

while the service2 is ovewritten by the application/xml


#3

In giving flexibility to the specification, we made a few things that may be ambiguous.

Given that the keys in a body are fixed: schema, example, formParameters and Content-type names always conform to the regex “.+/.+” I see no ambiguity in detecting if a body uses the defaultMediaType or not.

So to answer your comment:

Aside form the lack of description in the spec, this option means that you must look at the keys of the body property and determine whether they are mediate types and if and only if they are not, assume the user mean to use the default media type and that the keys are the body properties.

I would say, yes, you need to look one hop down the AST to determine the type