Suggestion to change how you define multiple examples

[VasiliyLysokobylko]

In the current RAML RC1 you can define multiple examples either using an array of -content keys or unique names followed by content. Both options are illustrated below:

types:
  Org:
    type: object
    properties:
      name: string
      address?: string
    examples: # multiple examples using an array of different contents
      - content:
          name: Acme
      - content:
          name: Software Corp
          address: 35 Central Street

types:
  Org:
    type: object
    properties:
      name: string
      address?: string
    examples: # multiple examples identified by their unique key names
      acme:
        content:
          name: Acme
      softwareCorp:
        content:
          name: Software Corp
          address: 35 Central Street

The first example using an array of -content keys is not valid according to YAML and should not be supported in the spec IMHO. The second uses unique keys which is fine, but we should remove content as it is not coherent to how you define a single example like the following:

types:
  Org:
    type: object
    properties:
      name: string
      address?: string
    example: # single example
      name: Software Corp
      address: 35 Central Street

My suggestion would be to use the same set of properties available in a single example also in examples except that each example needs to be identified by a unique key. The following is a modified version illustrates that:

types:
  Org:
    type: object
    properties:
      name: string
      address?: string
    examples: # multiple examples identified by their unique key names
      - acme:
          name: Acme
      - softwareCorp:
          name: Software Corp
          address: 35 Central Street

I am looking forward to hear some feedback.

[VasiliyLysokobylko]

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

[petrochenko-pavel-a]

Initial implementation is finished. (more testing is needed however)