Common Problems Found in RAML 1.0 API Specifications | MuleSoft Documentation
# Common Problems Found in RAML 1.0 API Specifications
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
## 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
## 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.
Back to the top
## 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
## 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
## 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
## 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
## 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
### 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"
   ]
```

=== 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
### 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
### 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
### 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`:
```
#%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:
```
#%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
## 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
## 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
## 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
```
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 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
## 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 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
### 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
## 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
## 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 1. Incorrect Examples vs. Corrected Examples Incorrect | Correct  
---|---  
```
#%RAML 1.0
title: Test
types:
 top:
  type: string
  minimum: 1
```
|  ```
#%RAML 1.0
title: Test
types:
 top:
  type: string
  minLength: 1
```
  
Incorrect | Correct  
---|---  
```
#%RAML 1.0
title: Test
invalidfacet:
version:
```
|  ```
#%RAML 1.0
title: Test
version:
```
  
Incorrect | Correct  
---|---  
```
#%RAML 1.0
title: Test
types:
 Prop:
  type: string
  required: false
 Obj:
  type: object
  properties:
   prop:
    type: Prop
```
|  ```
#%RAML 1.0
title: Test
types:
 Prop:
  type: string
 Obj:
  type: object
  properties:
   prop:
    type: Prop
    required: false
```
  
Back to the top
## 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 2. Incorrect Example vs. Corrected Example Incorrect | Correct  
---|---  
```
#%RAML 1.0
title: test
types:
 Device:
  type: [ Phone , Notebook ]
 Phone: string
 Notebook:
  type: object
  properties:
   manufacturer:
    type: string
```
|  ```
#%RAML 1.0
title: test
types:
 Phone: string
 Notebook:
  type: object
  properties:
   manufacturer:
    type: string
 Device:
  type: Phone | Notebook
```
  
Back to the top
### 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:
```
#%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
## 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.
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
## 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 3. Incorrect Example vs. Corrected Example Incorrect | Correct  
---|---  
```
#%RAML 1.0
title: test
types:
 SomeType: string
/endpoint:
 post:
  headers:
   MyHeader: someTypo
```
|  ```
#%RAML 1.0
title: test
types:
 SomeType: string
/endpoint:
 post:
  headers:
   MyHeader: someType
```
  
Back to the top
## 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:
```
#%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
## 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:
```
#%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
## 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