Common Problems Found in RAML 0.8 API Specifications

As of June 10, 2019, the code editor (one of the two editors in Design Center’s API Designer) uses stricter validation by default for RAML API-specification projects that were created before this date. If you open in the code editor a published API specification that is written in RAML 0.8, and you see violation (red) or warning (orange) messages. This list might help you to resolve the problems in your RAML.

Using a reserved name for a schema

If you use a reserved name as the name of a schema, the editor displays this message:

‘schemaName’ cannot be used to name a custom schema

Examples of reserved names are string, integer, number, and object. Any name that is used in the RAML specification cannot be used as the name for a schema.

For example, this API specification would cause the editor to display the message:

#%RAML 0.8

title: Example API Spec

schemas:
 string:
   type: string

To resolve the problem, you would need to use a different name in the schema declaration:

#%RAML 0.8

title: Example API Spec

schemas:
 customString:
   type: string

Problems when validating examples

Not using a data type of string for the example of a Boolean enum

Whether the values for a Boolean enum are both strings or Boolean values, the example of the enum must be a string. To illustrate the violation, this API specification shows an example using the wrong data type.

#%RAML 0.8
title: ExampleRAML
/nob:
  head:
    responses:
      204:
        headers:
          X-NOB-Exists:
            enum: [true, false]
            example: true

RAML 0.8 supports enum values as strings only, not as boolean values. Also, in the example RAML above, no data type for the enum is declared. In RAML 0.8, when a data type is not declared, it is assumed to be string.

Therefore, the values in the enum in the incorrect example above must be in quotation marks. That’s because the data type of an example must be the same as the data type of the element that it is an example of.

The last two lines of the example RAML above should then be as they are in this correction:

            enum: ["true", "false"]
            example: "true"

Not using a required property in the example of a schema that defines that property

If a schema defines a required property, the example of that schema must use that property. In this example of the problem, the following API specification defines a response for the endpoint /order/{id}. The definition includes two files: get_order_response_schema.json and get_order_response.json.

#%RAML 0.8
title: ExampleRAML
version: 1.0
...
/order:
  displayName: Orders API
  /create:
    ...

  /{id}:
    displayName: Get Order by OrderId
    description: This operation will get an order by order ID from Salesforce.
    get:
      description: This operation returns the order from Salesforce by Fulfillment Order ID, not by the Salesforce unique ID.
      responses:
        200:
          body:
            application/json:
              schema: !include get_order_response_schema.json
              example: !include get_order_response.json

The file get_order_response_schema.json defines the property's OrderId as a required property.

{
"type":"object",
"$schema": "http://json-schema.org/draft-03/schema",
"id": "http://com.mulesoft.demo.orders.get.json.order",
"required":false,
"properties":{
      ...
      "sfOrderId": {
        "type":"string",
        "id": "http://com.mulesoft.demo.orders.create.json.get.sfOrderId",
        "required":true
      },

The example of the schema is in get_order_response.json. However, the name of the required property is misspelled as sOrderId.

{
  "orderId": 14523,
  "sOrderId": "fadfead3524523",
  "sfAccountId": "fedfes3653635",
  "orderName": "Order From Manufacturing-Company, Inc.",
  "total": 174.92,
  "orderType": "E-Commerce Order",
  "description": "8 widgets",
  "orderDate": "04-03-2018"
}

Not using in an example of a schema the data type that the schema defines

For example, the schema in the following API specification defines the data type for the property title as an object; however, an array is used in the example of the schema.

#%RAML 0.8
title: ExampleRAML
schemas:
  - presentation: |
      {  "$schema": "http://json-schema.org/draft-03/schema",
         "type": "object",
         "properties": {
           "title":  { "type": "string" }
         }
      }

/presentations: &presentations
  type: { typedCollection: { schema: presentation } }
  get:
    responses:
      200:
       body:
         application/json:
           example: |
             [
              {
                  "title": "Presentation Video"
              },
              {
                  "title": "Environment Spec Report"
              }
              ]

Using 0 or 1 as the value of an example of a Boolean

An example for a Boolean must have a value of "true" or "false". In this API specification illustrating the violation, the value of the example for the form parameter is_public is incorrect.

#%RAML 0.8
title: ExampleRAML

/upload:
  post:
    description: |
      Upload a photo
    body:
      multipart/form-data:
        formParameters:
          title:
            description: The title of the photo.
          is_public:
            type: boolean
            example: 1

Not including a property in an example

If an example is missing a property of the type that it is exemplifying, the editor displays this violation message:

should have required property 'property name'

For example, the property age is missing in the example:

#%RAML 0.8
title: Example API Spec

/clients:
  get:
    responses:
      200:
        body:
          application/json:
            schema: |
              {
                "$schema": "http://json-schema.org/draft-03/schema",
                "properties": {
                    "firstName": {
                      "type": "string"
                    },
                    "lastName": {
                      "type": "string"
                    },
                    "age": {
                      "type": "number",
                      "required": true
                    }
                },
                "required": false,
                "type": "object"
              }
            example:
              firstName: John
              lastName: Smith

Either add the property to the example or, in the type declaration, declare the property as optional.

In this case, the property is added to the example:

#%RAML 0.8
title: Example API Spec

/clients:
  get:
    responses:
      200:
        body:
          application/json:
            schema: |
              {
                "$schema": "http://json-schema.org/draft-03/schema",
                "properties": {
                    "firstName": {
                      "type": "string"
                    },
                    "lastName": {
                      "type": "string"
                    },
                    "age": {
                      "type": "number",
                      "required": true
                    }
                },
                "required": false,
                "type": "object"
              }
            example:
              firstName: John
              lastName: Smith
              age: 30

In this case, the property is declared as optional:

#%RAML 0.8
title: Example API Spec

/clients:
  get:
    responses:
      200:
        body:
          application/json:
            schema: |
              {
                "$schema": "http://json-schema.org/draft-03/schema",
                "properties": {
                    "firstName": {
                      "type": "string"
                    },
                    "lastName": {
                      "type": "string"
                    },
                    "age": {
                      "type": "number",
                      "required": false
                    }
                },
                "required": false,
                "type": "object"
              }
            example:
              firstName: John
              lastName: Smith

Thank you!

To get in-depth knowledge on Mulesoft API, you can enroll for live Mulesoft training by OnlineITGuru with 24/7 support and lifetime access