---
schema_version: "1"
id: 4b4fec0e82d6d1890c0fa7e0c4054886ccf2154bbfd2e1a40a075a5168276ecf
title: Common Problems Found in RAML 1.0 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-10.md
canonical_url: https://docs.mulesoft.com/design-center/design-common-problems-raml-10
source_site: docs.mulesoft.com
content_type: documentation
content_hash: a8f9e9f0b9b4e9ea406f3d05f4210a281f5d0880ba5edef99631bae3d9c95e96
description: MuleSoft Documentation Site
latest: true
---
---
product: Design Center
---

# Common Problems Found in RAML 1.0 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
1.0, and tips for resolving them.

## Using the `schema` or `schemas` keyword instead of `type` or `types`

The specification for RAML 1.0 replaced the keywords `schema` and `schemas` with `type` and `types`.
If you use `schema` or `schemas`, the editor displays one of these warning messages:

‘schema' keyword it's deprecated for 1.0 version, should use 'type' instead

'schemas' keyword it's deprecated for 1.0 version, should use 'types' instead

For example, the following API specification generates both warning messages:

#%RAML 1.0 title: Incorrect API with schema and schemas

schemas: User: type: object properties: firstname: string lastname: string age: number

/users/{id}: get: responses: 200: body: application/json: schema: User

To resolve the problem, you would replace `schema` and `schemas` with `type` and `types`:

#%RAML 1.0 title: Correct API with type and types

types: User: type: object properties: firstname: string lastname: string age: number

/users/{id}: get: responses: 200: body: application/json: type: User

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

## Using a reserved name for a type

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

‘typeName’ cannot be used to name a custom type

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

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

#%RAML 1.0

title: Example API Spec

types: string: type: string

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

#%RAML 1.0

title: Example API Spec

types: customString: type: string

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

## Common misconceptions about examples and RAML NamedExample fragments

To avoid common problems with referencing a named example with an `!include` tag, follow these two
guidelines:

- In your API specification, use the `examples` facet and only one `!include` tag, as in this
  example:

  #%RAML 1.0 title: test types: A: properties: a: string b: integer examples: !include fragment.raml

- In the fragment, ensure that each example consists of a name and values for each property, as in
  the fragment below:

  fragment.raml

  #%RAML 1.0 NamedExample myExample1: a: "b1" b: 1

  myExample2: a: "b2" b: 2

For a more detailed discussion of how to use named examples, see
[Guide to Defining Examples in RAML 1.0](https://docs.mulesoft.com/design-center/design-named-examples).

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

## Appending references with hash symbols to filenames in `!include` statements

A filename cannot be followed by a hash symbol and a reference to a location within the named file.
In this example, `IncrementType.raml#increment` is not a valid link.

#%RAML 1.0 DataType

type: object properties: startValue: integer endValue: integer exclusiveEndValue: boolean range:
type: array items: !include IncrementType.raml#increment

If your specification contains an violation of this type, but you meant to write a comment, place an
empty space before the "#" symbol. If you meant to reference an element that is in the file, such
references are not allowed. References to inner elements are valid only for XSD and JSON schemas.

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

## Not correctly using curly braces and brackets in JSON examples

There are many ways to misuse curly braces and brackets. This example illustrates one of them. An
array of groups of JSON key/value pairs is improperly enclosed in a pair of curly braces.

#%RAML 1.0 title: ExampleRAML ... /rooms: displayName: rooms get: description: get all rooms
responses: 200: body: application/json: example: | { \[{ "Name": "Superior King", "Number": "201",
"Property": "SE030", "Status": "Clean" }, { "Name": "Junior Suite", "Number": "202", "Property":
"NO131", "Status": "Clean" }\] }

If the example was meant be an object, then a key must be specified for it.

#%RAML 1.0 title: ExampleRAML ... /rooms: displayName: rooms get: description: get all rooms
responses: 200: body: application/json: example: { "some\_key": \[ { "Name": "Superior King",
"Number": "201", "Property": "SE030", "Status": "Clean" }, { "Name": "Junior Suite", "Number":
"202", "Property": "NO131", "Status": "Clean" } \] }

If the example was meant be an array, then the outside curly braces must be removed.

#%RAML 1.0 title: ExampleRAML ... /rooms: displayName: rooms get: description: get all rooms
responses: 200: body: application/json: example: \[ { "Name": "Superior King", "Number": "201",
"Property": "SE030", "Status": "Clean" }, { "Name": "Junior Suite", "Number": "202", "Property":
"NO131", "Status": "Clean" } \]

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

## Referencing libraries by using the `type` key

As explained in the RAML 1.0 specification, you must apply libraries with the `uses` node:

> Any number of libraries can be applied by using the OPTIONAL `uses` node ONLY at the root of a
> \["main"\] RAML or RAML fragment file. The value of the \`use\`s node is a map of key-value pairs.
> The keys are treated as library names, or namespaces, and the value MUST be the location of a RAML
> library file, usually an external RAML library fragment document.

If you apply a library with a `type` node, the editor displays this message:

Libraries must be applied by using 'uses'

Therefore, the following example is incorrect, given that the file `financeDetail.raml` is a
library.

#%RAML 1.0 title: ExampleRAML ... /claims: /{claim-id}: patch: body: application/json: type:
!include financeDetail.raml

This next example is correct.

#%RAML 1.0 title: ExampleRAML uses: lib: financeDetail.raml /claims: /{claim-id}: patch: body:
application/json: type: lib.myType

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

## Problems when validating examples

### 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 1.0 title: Example API Spec

types: User: type: object properties: firstName: string lastName: string age: integer 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 1.0 title: Example API Spec

types: User: type: object properties: firstName: string lastName: string age: integer example:
firstName: John lastName: Smith age: 49

In this case, the property is declared as optional:

#%RAML 1.0 title: Example API Spec

types: User: type: object properties: firstName: string lastName: string age?: integer example:
firstName: John lastName: Smith

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

### Specifying values for an enum that does not match the enum’s data type

Because of the editor’s strict parsing according to the YAML specification, it does not
automatically cast values to declared data types. To illustrate the violation, here is an invalid
declaration of an enum:

type: string enum: \[1,2,3\]

The data type for the enum is `string`; however, the values are all integers. Because the editor
stricly parses according to the YAML specification, it does not cast the integers to `string` values
automatically. Therefore, either the type is declared incorrectly in this example and should be
`integer`, or the enum values need to be in quotation marks.

Here is another invalid declaration:

type: string enum: \[ "a", "b", "c", false, 3.0 \]

The value `false` is a `boolean`, while the value `3.0` is a `float`. Neither is converted to a
`string` value by the editor.

The next three declarations are valid.

type: string enum: \["1","2","3"\]

type: integer enum: \[1,2,3\]

type: string enum: \[ "a", "b", "c", "false", "3.0" \]

> [!NOTE] \=== This violation can occur not just in enums, but also anywhere an `integer`, `nil`
> value, or value of some other data type is introduced where the parser expects a `string` value.
> ===

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

### Using, in an example of a numeric type, an incorrect format for that type, if a format is specified

Examples of numeric types must conform to restrictions specified in the `format` node. In this
example of the violation, the format specified for the numeric type `collection` is int8. However,
the value of the example is greater than 127.

#%RAML 1.0 title: ExampleRAML types: collection: type: integer format: int8

/search: /code: get: body: application/json: type: collection example: 22342342

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

### Including undeclared properties in an example when additionalProperties is set to `false`

If an example for a type includes one or more properties that were not in the type declaration, the
editor displays this message:

should NOT have additional properties

The editor would display this message for the following API specification:

#%RAML 1.0 title: Example API Spec

types: User: type: object additionalProperties: false properties: firstName: string lastName: string
example: firstName: John lastName: Smith age: 49

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

- Delete the extra property from the example

  #%RAML 1.0 title: Example API Spec

  types: User: type: object additionalProperties: false properties: firstName: string lastName:
  string example: firstName: John lastName: Smith

- Add the property in the type declaration.

  #%RAML 1.0 title: Example API Spec

  types: User: type: object additionalProperties: false properties: firstName: string lastName:
  string age: integer example: firstName: John lastName: Smith age: 49

- Change the value of `additionalProperties` to `true` or remove the line for `additionalProperties`
  (because `additionalProperties` is `true` by default).

  #%RAML 1.0 title: Example API Spec

  types: User: type: object properties: firstName: string lastName: string additionalProperties:
  true example: firstName: John lastName: Smith age: 49

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

### Types defined as `nil` in payloads are not valid

You cannot use a type in a payload if its data type is `nil`.

#### Example 1

In this example, the value of `type` must be `string`, not `nil`:

```none
#%RAML 1.0
title: test

types:
  MyType:
    type: nil
    example: “test”
```

#### Example 2

In this example, the JSON schema must define `MyType` as a `string` type. However, the schema is
empty:

```none
#%RAML 1.0
title: test

types:
  MyType:
    type: !include schema.json # schema.json is an empty file
    example: “test”
```

The error message in cases like this is `should be null at …​`.

[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 1.0 title:

[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 1.0 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 1.0 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 1.0 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 1.0 title: Example API Spec /media: get: responses: 200: body: application/json: type:
  string

- Specify the default media type globally for the API specification.

  #%RAML 1.0 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 1.0 title: New API mediaType: \[ application/json, application/xml \] types: Person: Another:
/list: get: responses: 200: body: Person\[\] /send: post: body: application/json: type: 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 an example response that contains invalid JSON

When a JSON file is included as the example of a response message, the JSON in the file must be
valid. In this example of the violation, the example of the response for the 200 response code
contains an `!include` statement. The JSON in the included file incorrectly contains a comma after
the last key/value pair.

#%RAML 1.0 title: ExampleRAML ... /resume: description: "Gets candidate's resume." get:
queryParameters: ... headers: ... responses: 200: body: application/json: example: !include
exampleResumeData-200.json 500: ...

{ ... "assessments.characteristic.focusofattention.data"= "", }

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

### Not providing a YAML map when a facet requires one

When a facet is described in the RAML 1.0 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 1.0 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 1.0 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 1.0 title: Test version: 1.0 securitySchemes: basic: type: Basic Authentication

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

## Not defining a type that is used

When a type is used, but is not first defined, the editor returns the message
`Unresolved reference`.

In this example of the error, the type `mytype` is not defined.

#%RAML 1.0

title: test /path: post: responses: 200: body: application/json: type: mytype

To resolve the problem, define the type that you are using.

#%RAML 1.0

title: test types: mytype: string /path: post: responses: 200: body: application/json: type: mytype

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

## Using an unsupported property

This error occurs when a facet or data type is defined as having a specific set of properties, yet
an API specification defines the facet with a property that is not in that set. The error can also
occur if you use an undefined facet.

Example error message \* `Property minimum not supported in a RAML 1.0 stringScalarShape node`,
where `minimum` is the name of the unsupported property. A `string` does not have a minimum value.
\* `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 are examples that would generate these errors:

<table><caption>Table 1. Incorrect Examples vs. Corrected Examples</caption> <colgroup><col> <col></colgroup><thead><tr><th>Incorrect</th><th>Correct</th></tr></thead><tbody><tr><td><div><div><div><pre>#%RAML 1.0
title: Test
types:
  top:
    type: string
    minimum: 1</pre></div></div></div></td><td><div><div><div><pre>#%RAML 1.0
title: Test
types:
  top:
    type: string
    minLength: 1</pre></div></div></div></td></tr></tbody></table>

<table><colgroup><col> <col></colgroup><thead><tr><th>Incorrect</th><th>Correct</th></tr></thead><tbody><tr><td><div><div><div><pre>#%RAML 1.0
title: Test
invalidfacet:
version:</pre></div></div></div></td><td><div><div><div><pre>#%RAML 1.0
title: Test
version:</pre></div></div></div></td></tr></tbody></table>

<table><colgroup><col> <col></colgroup><thead><tr><th>Incorrect</th><th>Correct</th></tr></thead><tbody><tr><td><div><div><div><pre>#%RAML 1.0
title: Test
types:
  Prop:
    type: string
    required: false

Obj: type: object properties: prop: type:
Prop</pre></div></div></div></td><td><div><div><div><pre>#%RAML 1.0 title: Test types: Prop: type:
string

Obj: type: object properties: prop: type: Prop required:
false</pre></div></div></div></td></tr></tbody></table>

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

## Invalid Type Inheritance

Two common occurrences that cause type-inheritance errors are incorrectly merging two types and
defining a weaker constraint in a subtype.

### Merging Two types incorrectly

This type of error occurs when you try to perform one of these actions:

- Merge a defined type with an undefined type

- Merge two undefined types

The error also occurs when you try to perform a merge with the wrong syntax.

Example error message

`Resolution error: Incompatible types [class amf.plugins.domain.shapes.models.ScalarShape, class amf.plugins.domain.shapes.models.NodeShape]`

The following example both tries to merge two undefined types and uses incorrect syntax for the
merge. The resolution of the error involves defining the types before the merge, and also using a
pipe for the merge syntax, not brackets and a comma.

<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 1.0
title: test
types:
  Device:
    type: [ Phone , Notebook ]
  Phone: string
  Notebook:
    type: object
    properties:
      manufacturer:
        type: string</pre></div></div></div></td><td><div><div><div><pre>#%RAML 1.0
title: test
types:
  Phone: string
  Notebook:
    type: object
    properties:
      manufacturer:
        type: string
  Device:
    type: Phone | Notebook</pre></div></div></div></td></tr></tbody></table>

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

### Defining a Weaker Constraint in a Subtype

A subtype that defines a weaker constraint than one defined by its parent type is invalid.

In this example, the subtype MyType2 has the optional property `name`, defined as a string, even
though the parent type MyType1 already defines its `name` property as required:

```none
#%RAML 1.0
title: test

types:
  MyType1:
    properties:
      name: string
  MyType2:
    type: MyType1
    properties:
      name?: string #invalid
```

The error message in cases like this is
`Resolution error: sub type has a weaker constraint for minItems than base type for minItems.`

[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. To fix the error, specify a
type that is defined in the RAML specification.

Error message

`Cannot declare unresolved parameter`

In the incorrect example below, the value for the header `myHeader` has a typo. It is specified as
`someTypo`, not as `someType`.

<table><caption>Table 3. 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 1.0
title: test
types:
  SomeType: string
/endpoint:
  post:
    headers:
      MyHeader: someTypo</pre></div></div></div></td><td><div><div><div><pre>#%RAML 1.0
title: test
types:
  SomeType: string
/endpoint:
  post:
    headers:
      MyHeader: someType</pre></div></div></div></td></tr></tbody></table>

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

## Using a Forward Slash in a URI Parameter

A URI parameter that contains a forward slash (/) is invalid.

In this example, the `example` for the URI parameter `transaction-Date` would cause the parser to
display an error message:

```none
#%RAML 1.0
title: test

/endpoint:
  uriParameters:
    transaction-Date:
      example: 01/02/2018
```

The error message in cases like this is
`Value '01/02/2018' of uri parameter must not contain '/' character.`

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

## Incorrect Formats for `datetime` Types

Formats for `datetime` types that do not use "rfc3339" or "rfc2616" are invalid.

The following example causes the parser to display an error message:

```none
#%RAML 1.0
title: test
types:
  MyType:
    type: datetime
    format: "rfc3338"
```

The error message in cases like this is
`Invalid format value for datetime, must be ‘rfc3339’ or ‘rfc2616’.`

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

## Absolute Paths in RAML Fragment Projects

When adding dependencies using absolute paths (for example: `(!include /examples/200.json)`) in RAML
Fragment projects, you get a validation error: `Resource /examples/200.json not found`.

You must always use relative paths for RAML Fragment Projects, for example:
`(!include ../examples/200.json)`.

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