Properly create a RAML 1.0 Named Example

Question

I am using RAML 1.0 to specify an API, but having trouble working with the Named Example fragment type. I've looked at numerous tutorials and examples, but cannot find a definitive guide to what's expected in this resource.

I'm working with the MuleSoft Anypoint Platform API Designer. (May 2020)

Here is my DataType definition:

#%RAML 1.0 DataType
type: object
properties:
  display-name: 
    required: true
    type: string
  note-properties:
    required: true
    type: object
  note-data:
    required: true
    type: any

Here is my Named Example fragment:

#%RAML 1.0 NamedExample
noteExample:
    display-name: greeting
    note-properties: read-only
    note-data: Hello world

And here is the root file that references these:

#%RAML 1.0
title: sandbox API

types:
  noteType: !include definitions/noteType.raml

/note:
  get:
    responses:
      200:
        body:
          application/json:
            type: noteType
            examples: !include examples/noteExample.raml

The issue is that the parser (APIKit plugin) reports this as an error. Here is the error message from Design Center:

['note-properties'] should be object at /examples/noteExample.raml (3, 1)

I've also tried a simpler DataType definition, but I get the same error.

Is there an obvious error in my Named Example file. I know there must be a definitive spec, but so far what I find are various (occasionally conflicting) examples.

...it turns out that if I read it more slowly, and after having tried some unsuccessful things, that this page (docs.mulesoft.com/design-center/design-named-examples) helped a bit. — agentv

agentv agentv · Accepted Answer · 2020-05-12T02:55:23

...okay, this is embarrassing. The error message tells exactly what is wrong.

It clearly says "XXX should be an object"

When I changed the Named Example to this:

#%RAML 1.0 NamedExample
  noteExample:
      display-name: greeting
      note-properties: 
        status: read-only
      note-data: Hello world

...where the value presented for

note-properties

is an actual object instead of a simple string (as it was in my OP), then that worked just fine.

Properly create a RAML 1.0 Named Example

1 Answers