Bodies property

[dmartinezg]

Bodies property

RAML 1.0 should allow the following:

• Allow more than one example for each schema
• Give a way to tie schemas and examples as bundles to avoid duplication in resource definitions
• Allow specifying the type of a schema explicitly

A body definition

A body can be used to describe the body of a request or the body of a response. It is a map with the following properties:

Property Name	Description
schema	A mapping with the schema definition
example	A string with a single example for the body.
examples	A mapping of examples, where the key is the name of the example

An example is a simple map with the following properties

Property Name	Description
description	A string with a short description of the example.
example	A string with a single example for the body.

A schema is a simple map with the following properties

Property Name	Description
type	A string describing the language in which the resource is described: valid values for this field are json-schema/draft-03, json-schema/draft-04, xml-schema.
definition	A string with the schema definition written in the language and syntax described by schemaType.

Bodies

Add a root property bodies, is a map, each key in it, is the name of a body, each value is a map with a body definition.

Using bodies

Now, when a RAML creator wants to use a body, it has a choice of defining the body as described above, or reference a root level body defined by name in the bodies root level property.

In the following example, 2 bodies are defined, user and users, both are referenced automatically from a resourceType, using resourcePathName, and user is also referenced from the /users/me resource.

title: My Sample API
defaultMediaType: application/json
bodies:
  user:
    schema:
      type: json-schema/draft-03
      definition: |
        {}
    examples:
      adminUser:
        description: An `admin` user has the `admin` property set to `true` and has the `allowed-operations` collection populated with the all the actions it can perform
        example: |
          { an example of the JSON here }
      normalUser:
        description: A `normal` user does not have the `admin` property turned on.
        example: |
          { an example of the JSON here }
  users:
    schema:
      type: json-schema/draft-03
      definition: |
        {}
    example: |
      { an example of the JSON here }
resourceTypes:
  collection:
    post:
      body: <<resourcePathName!singularize>>
    get:
      body: <<resourcePathName>>
/users:
  type: collection
  /me:
    get:
      responses:
        200:
          body: user

[cybertk]

Great, expecting RAML 1.0.

[svacas]

should the spec enforce the list of mime types that are allowed for each schema type?

e.g: for type xml-schema: text/xml, application/xml, (.*)/(.*)+xml

[sichvoge]

I think that issue has been resolved by introducing the new type system for data modelling #167. The type systems helps to define multiple examples, it bundles the model to an example and it's definition, and it has to ability to define an explicit type for a model. My suggestion would be to mark that as "v1.0 - tentatively subsumed by other candidates"