Contact Free trial Login

Common Problems Found in RAML 1.0 API Specifications

As of January 10, 2019, the code editor (one of the two editors in Design Center’s API Designer) uses stricter validation by default for RAML API-specification projects that were create before this date. If you open in the code editor a published API specification that is written in RAML 1.0, and you see violation (red) or warning (orange) messages, this list might help you to resolve the problems in your RAML.

After a grace period that lasts at least until January 10, 2020, you will not be able to publish API specifications that generate any violation messages.

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

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

Problems with named examples

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 NamedExample fragment, ensure that each example consists of a name and a value, as in the fragment below that contains one example:

    #%RAML 1.0 NamedExample
    myExample:
        a: "b"
        b: 1

For a more detailed discussion of how to use named examples, see Guide to Named Examples.

Naming examples twice

If an example is named twice, the editor displays this message:

should have required property '<name-of-property>'

For example, suppose that a specification defines the property firstName and links to a NamedExample fragment by giving the example the name someName:

#%RAML 1.0
title: Example API Spec
/tiers:
 post:
   body:
     application/json:
       properties:
         firstName: string
       examples:
         someName: !include ex.raml

Further suppose that the NamedExample fragment also names the example, giving it the name someFragmentName:

#%RAML 1.0 NamedExample
someFragmentName:
  firstName: Martin Gutierrez

In this case, the editor would display this message because the parser interprets someFragmentName as the name of the property:

should have required property 'firstName'

To resolve this type of problem, remove either the name in the examples facet in the specification or the name in the NamedExample fragment.

If you choose to remove the name from the NamedExample fragment, you must remove the word "NamedExample" from the declaration in the fragment. For example, you would change the NamedExample fragment used in the situation above to look like this:

#%RAML 1.0
firstName: Martin Gutierrez

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.

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"
          	}
            ]

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 ["master"] 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

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

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

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

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

Not providing a value for the title node

The title node cannot lack a value, as it does here:

#%RAML 1.0
title:

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

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

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'

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'

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:
        ...
{
...
"assesments.characteristic.focusofattention.data"= "",
}

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

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

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
invalidfacet:
version:
#%RAML 1.0
title: Test
types:
  top:
    type: string
    minLength: 1

#%RAML 1.0
title: Test
version:

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

For more information, see the section "Union Types" in the RAML 1.0 specification.

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