Common Problems Found in RAML 0.8 API Specifications | MuleSoft Documentation
# 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
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
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
### Not providing a YAML map when a facet requires one
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.
Back to the top
### Not providing a YAML map when a facet requires one
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