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

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

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

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
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

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

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.

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

Common Problems Found in RAML 1.0 API Specifications

Using the schema or schemas keyword instead of type or types

Using a reserved name for a type

Common misconceptions about examples and RAML NamedExample fragments

Appending references with hash symbols to filenames in !include statements

Not correctly using curly braces and brackets in JSON examples

Referencing libraries by using the type key

Problems when validating examples

Not including a property in an example

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

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

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

Types defined as nil in payloads are not valid

Example 1

Example 2

Not providing a value for the title node

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 an example response that contains invalid JSON

Not providing a YAML map when a facet requires one

Not defining a type that is used

Using an unsupported property

Invalid Type Inheritance

Merging Two types incorrectly

Defining a Weaker Constraint in a Subtype

Declaring an undefined type in a header

Using a Forward Slash in a URI Parameter

Incorrect Formats for datetime Types

Absolute Paths in RAML Fragment Projects

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

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

Referencing libraries by using the `type` key

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

Types defined as `nil` in payloads are not valid

Not providing a value for the `title` node

Not referencing fragments by using the `!include` tag

Not applying libraries by using the `uses` key

Incorrect Formats for `datetime` Types