---
schema_version: "1"
id: da9696894e87c39cc34348bd2e90802c6034d09875abe6f695002c63e05f65d0
title: Common Problems Found in RAML 0.8 API Specifications
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/design-center/design-common-problems-raml-08.md
canonical_url: https://docs.mulesoft.com/design-center/design-common-problems-raml-08
source_site: docs.mulesoft.com
content_type: documentation
content_hash: 27de4d4f871d2780ca5d1c329bbdc3baad7eabb44b5f7cbba5147d3202ec53be
description: MuleSoft Documentation Site
latest: true
---
---
product: Design Center
---

# Common Problems Found in RAML 0.8 API Specifications

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

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](#bookmark-a)

## 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](#bookmark-a)

### 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](#bookmark-a)

### 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](#bookmark-a)

### 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](#bookmark-a)

[Back to the top](#bookmark-a)

## 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](#bookmark-a)

## 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](#bookmark-a)

## 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](#bookmark-a)

## 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](#bookmark-a)

## 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](#bookmark-a)

## 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](#bookmark-a)

## 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](#bookmark-a)

## 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](#bookmark-a)

### 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](#bookmark-a)

### 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](#bookmark-a)

## 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><caption>Table 1. Incorrect Example vs. Corrected Example</caption> <colgroup><col> <col></colgroup><thead><tr><th>Incorrect</th><th>Correct</th></tr></thead><tbody><tr><td><div><div><div><pre>#%RAML 0.8
title: Test
invalidfacet:
version:</pre></div></div></div></td><td><div><div><div><pre>#%RAML 0.8
title: Test
version:</pre></div></div></div></td></tr></tbody></table>

[Back to the top](#bookmark-a)

## 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><caption>Table 2. Incorrect Example vs. Corrected Example</caption> <colgroup><col> <col></colgroup><thead><tr><th>Incorrect</th><th>Correct</th></tr></thead><tbody><tr><td><div><div><div><pre>#%RAML 0.8
title: test

/endpoint: post: headers: myHeader:
strang</pre></div></div></div></td><td><div><div><div><pre>#%RAML 0.8 title: test

/endpoint: post: headers: myHeader: string</pre></div></div></div></td></tr></tbody></table>

[Back to the top](#bookmark-a)