[SOLVED] RAML: example vs examples

RAML: example vs examples

While doing Walkthrough 3-3 in mule 4 developer training, I am unable to understand why RAML facet examples works but example doesn't.

Environment: Anypoint-Design Centre - API Designer RAML 1.0

Errors : "Error: should have required property 'code' should have required property 'departureDate' should have required property 'destination' should have required property 'emptySeats' should have required property 'origin' should have required property 'price' "

This is the relevant extract from REST API RAML spec.

   /{ID}:
    get:
      responses:
        200:
          body:
            application/json:
              type: AmericanFlight
              example:
                output: !include examples/AmericanFlightExample.raml

But if I change example to examples it works. Since the uri is expected to retrieve one and not many, I am under the impression facet = "example:" is correct. Also, for using facet= "examples:" I would think the response should be an array (type: AmericanFlight[]) and the example raml to include multiple items. Following is the example raml

#%RAML 1.0 NamedExample
value:
    ID: 1 
    code: ER38sd
    price: 400
    departureDate: 2017/07/26
    origin: CLE
    destination: SFO
    emptySeats: 0
    plane: 
      type: Boeing 737
      totalSeats: 150

Can someone help me understand why this is so?

Solution

This is a common confusion using RAML because of assuming the plural means multiples examples as an array and that NamedExample means something different.

example: is for a single example where you just add or include the values of the properties. Only contains the values of the object's properties (RAML 1.0 spec link).
examples: is for multiple examples as a map, where each key is the name of the example (RAML 1.0 spec link). That means an array is not a valid type for this facet.

Note that in your example value: is the name of an example, not a property. As an example if you add a second example to that file it could have key value2:.

This confusion is so common that MuleSoft documentation has some pages to clarify RAML examples and common misconceptions.