Common Problems Found in RAML 0.8 API Specifications

The following sections describe common errors authors make when writing API specifications in RAML 0.8, and tips for resolving them.

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

Back to the top

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 line of the example RAML above should then be as they are in this correction:

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

Back to the top

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 sfOrderId 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"
}

Back to the top

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"
              }
              ]

Back to the top

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

Back to the top

Not providing a value for the `title` node

The title node cannot lack a value, as it does here:

#%RAML 0.8
title:

Back to the top

Not using the data type of the RAML element in the example for that element

In all cases, the data type of an example must match the data type of the element that it is an example of.

In this incorrect API specification, a query parameter is defined as a string; however, the example of the query parameter is an integer.

#%RAML 0.8
title: ExampleRAML
/books:
  get:
    queryParameters:
      publicationYear:
        type: string
        example: 2016

Back to the top

Using an invalid path for a reference inside a JSON schema

When you use the $ref keyword in a JSON schema, the path that you specify with it must start at the root of the schema. For example, the $ref keyword used for the property input2 in the following schema uses an incorrect path to refer to the property input.

#%RAML 0.8
title: ExampleRAML
version: v1
schemas:
- authCodeResponse : |
    {
      "$schema": "http://json-schema.org/draft-04/schema",
      "properties": {
        "input": {
          "type": "string"
        },
        "input2": {
          "$ref": "input"
        }
      },
       "type": "object"
    }

The path must start at the root level of the schema and descend through the tree structure. This example of the schema shows the same $ref keyword using the correct path.

{
      "$schema": "http://json-schema.org/draft-04/schema",
      "properties": {
        "input": {
          "type": "string"
        },
        "input2": {
          "$ref": "#/properties/input"
        }
      },
       "type": "object"
    }

Back to the top

Declaring a URI parameter that is never used

If an API specification declares a URI parameter, but then does not use that parameter, the editor displays this warning message:

unused uri parameter “parameter”

If the parameter is declared as a base URI parameter, but is not used, then this is the warning message:

unused base uri parameter “parameter”

For example, the following API specification would generate two warning messages:

unused uri parameter "unusedParam"

unused base uri parameter "unusedUriParam"

#%RAML 0.8
title: test

baseUri: http://param.raml/a/{baseUriParam1}/{nonExists}/{baseUriParam2}

baseUriParameters:
 baseUriParam1:
    type: string
 baseUriParam2:
    type: string
 unusedParam:
    type: string

/endpoint/{uriParam1}/{nonExistsUri}:
 uriParameters:
   uriParam1:
     type: string
   unusedUriParam:
     type: string

To resolve the warning messages, you would simply need to remove the lines that declare these parameters:

#%RAML 0.8
title: test

baseUri: http://param.raml/a/{baseUriParam1}/{nonExists}/{baseUriParam2}

baseUriParameters:
 baseUriParam1:
   type: string
 baseUriParam2:
     type: string

/endpoint/{uriParam1}/{nonExistsUri}:
 uriParameters:
   uriParam1:
     type: string

Back to the top

Not declaring a media type for a payload

If the declaration of a payload does not declare a media type, the editor displays this message:

Payload media type is mandatory

For example, the editor would display this message for the following API specification:

#%RAML 0.8
title: Example API Spec
/media:
 get:
   responses:
     200:
       body:
         type: string

There are two methods that you can choose from to resolve the problem:

Declare the media type locally in the payload declaration.

#%RAML 0.8
title: Example API Spec
/media:
 get:
   responses:
     200:
       body:
        application/json:
         type: string

Specify the default media type globally for the API specification.

#%RAML 0.8
title: Example API Spec

mediaType: application/json

/media:
 get:
   responses:
     200:
       body:
         type: string

The following example uses both a global and a local declaration. In this case, the mediaType node defines acceptable media types as application/json and application/xml. The first type, Person, returns a body that is in either media type. However, the second type, Another, overrides the global declaration with a local one, and returns only a JSON body.

#%RAML 0.8
title: New API
mediaType: [ application/json, application/xml ]
schemas:
  Person:
  Another:
/list:
  get:
    responses:
      200:
        body: Person
/send:
  post:
    body:
      application/json:
        schema: Another

Back to the top

Not referencing fragments by using the `!include` tag

If an API specification uses the key uses to reference fragments, the editor displays this message:

Fragments must be imported by using '!include'

Back to the top

Not applying libraries by using the `uses` key

If an API specification uses the !include tag to apply a library, the editor displays this message:

Libraries must be applied by using 'uses'

Back to the top

Problems with syntax

Including a schema that contains invalid JSON

The JSON in files that are included in the value of the schemas property must be valid.

The first example includes the schema appSwitcher.json. However, the second shows that there is an error in the JSON: at the end of the last value, there is a comma, though there should instead be a quotation mark.

#%RAML 0.8
title: ExampleRAML
schemas:
  - appSwitcher: !include schemas/appSwitcher.json

{
  "appMenuItems" : [
    {
      "type" : "Tabset" ,
      "content" : null ,
      "icons" : null ,
      "colors" : null ,
      "label" : "Call Center" ,
      "url" : "/home/home.jsp?tsid=02uxx00000056Sr"
    } , {
      "type" : "Tabset" ,
      "content" : null ,
      "icons" : null ,
      "colors" : null ,
      "label" : "Community" ,
      "url" : "/home/home.jsp?tsid=02uxx00000056Sw"
    } , {
      "type" : "Tabset" ,
      "content" : null ,
      "icons" : null ,
      "colors" : null ,
      "label" : "App Launcher" ,
      "url" : "/app/mgmt/applauncher/appLauncher.apexp?tsid=02uxx00000056Sx,
    }
  ]
}

Back to the top

Using invalid JSON in examples of JSON schemas

Examples of JSON schemas must be valid, unlike the example in the following API specification:

#%RAML 0.8
title: ExampleRAML
...
/api:
  get:
    responses:
      200:
        body:
          application/json:
            schema:
              {
                "type": "object",
                "required": true,
                "$schema": "http://json-schema.org/draft-03/schema",
                "properties": {
                  "a": {
                    "type": "boolean",
                    "required": true
                  }
                }
              }
            example:
              {
                "a: {
                  "a": ""
                }

Back to the top

When a facet is described in the RAML 0.8 specification as requiring a map as a value, but the API specification doesn’t provide a map, the editor returns the message YAML map expected.

Here is an example of the error:

#%RAML 0.8
title: Test
version: 1.0
securitySchemes:
  basic:
    type: Basic Authentication
    settings:

There are two ways to fix the error.

Provide a map as a value.

#%RAML 0.8
title: Test
version: 1.0
securitySchemes:
  basic:
    type: Basic Authentication
    settings:
      requestTokenUri: https://api.mysampleapi.com/1/oauth/request_token

Delete the facet — in this case, settings — that requires a map.

#%RAML 0.8
title: Test
version: 1.0
securitySchemes:
  basic:
    type: Basic Authentication

Back to the top

Using an unsupported property

This error occurs if you use an undefined facet.

Example error message: Property invalidfacet not supported in a RAML 0.8 webApi node, where invalidfacet is the name of a facet that is not defined in the RAML specification.

Here is an example that would generate this error:

Table 1. Incorrect Example vs. Corrected Example
Incorrect	Correct
#%RAML 0.8 title: Test invalidfacet: version:	#%RAML 0.8 title: Test version:

Back to the top

Declaring an undefined type in a header

This error occurs when a non-existent type is specified in a header.

Error message: Cannot declare unresolved parameter

In the incorrect example below, the value for the header myHeader has a typo. It is specified as strang, not as string.

Table 2. Incorrect Example vs. Corrected Example
Incorrect	Correct
#%RAML 0.8 title: test /endpoint: post: headers: myHeader: strang	#%RAML 0.8 title: test /endpoint: post: headers: myHeader: string

Back to the top

Common Problems Found in RAML 0.8 API Specifications

Using a reserved name for a schema

Problems when validating examples

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

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

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

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

Not including a property in an example

Not providing a value for the title node

Not using the data type of the RAML element in the example for that element

Using an invalid path for a reference inside a JSON schema

Declaring a URI parameter that is never used

Not declaring a media type for a payload

Not referencing fragments by using the !include tag

Not applying libraries by using the uses key

Problems with syntax

Including a schema that contains invalid JSON

Using invalid JSON in examples of JSON schemas

Not providing a YAML map when a facet requires one

Using an unsupported property

Declaring an undefined type in a header

Not providing a value for the `title` node

Not referencing fragments by using the `!include` tag

Not applying libraries by using the `uses` key