‘schemaName’ cannot be used to name a custom schema
Common Problems Found in RAML 0.8 API Specifications
The following sections describe common errors authors make when writing API specifications in RAML 0.8, and tips for resolving them.
Using a reserved name for a schema
If you use a reserved name as the name of a schema, the editor displays this message:
Examples of reserved names are string
, integer
, number
, and object
. Any name that is used in the RAML specification cannot be used as the name for a schema.
For example, this API specification would cause the editor to display the message:
#%RAML 0.8 title: Example API Spec schemas: string: type: string
To resolve the problem, you would need to use a different name in the schema declaration:
#%RAML 0.8 title: Example API Spec schemas: customString: type: string
Problems when validating examples
Not using a data type of string for the example of a Boolean enum
Whether the values for a Boolean enum are both strings or Boolean values, the example of the enum must be a string. To illustrate the violation, this API specification shows an example using the wrong data type.
#%RAML 0.8 title: ExampleRAML /nob: head: responses: 204: headers: X-NOB-Exists: enum: [true, false] example: true
RAML 0.8 supports enum values as strings only, not as boolean values. Also, in the example RAML above, no data type for the enum is declared. In RAML 0.8, when a data type is not declared, it is assumed to be string
.
Therefore, the values in the enum in the incorrect example above must be in quotation marks. That’s because the data type of an example must be the same as the data type of the element that it is an example of.
The last two line of the example RAML above should then be as they are in this correction:
... enum: ["true", "false"] example: "true"
Not using a required property in the example of a schema that defines that property
If a schema defines a required property, the example of that schema must use that property. In this example of the problem, the following API specification defines a response for the endpoint /order/{id}
. The definition includes two files: get_order_response_schema.json
and get_order_response.json
.
#%RAML 0.8 title: ExampleRAML version: 1.0 ... /order: displayName: Orders API /create: ... /{id}: displayName: Get Order by OrderId description: This operation will get an order by order ID from Salesforce. get: description: This operation returns the order from Salesforce by Fulfillment Order ID, not by the Salesforce unique ID. responses: 200: body: application/json: schema: !include get_order_response_schema.json example: !include get_order_response.json
The file get_order_response_schema.json
defines the property sfOrderId
as a required property.
{ "type":"object", "$schema": "http://json-schema.org/draft-03/schema", "id": "http://com.mulesoft.demo.orders.get.json.order", "required":false, "properties":{ ... "sfOrderId": { "type":"string", "id": "http://com.mulesoft.demo.orders.create.json.get.sfOrderId", "required":true }, ...
The example of the schema is in get_order_response.json
. However, the name of the required property is misspelled as sOrderId
.
{ "orderId": 14523, "sOrderId": "fadfead3524523", "sfAccountId": "fedfes3653635", "orderName": "Order From Manufacturing-Company, Inc.", "total": 174.92, "orderType": "E-Commerce Order", "description": "8 widgets", "orderDate": "04-03-2018" }
Not using in an example of a schema the data type that the schema defines
For example, the schema in the following API specification defines the data type for the property title
as an object; however, an array is used in the example of the schema.
#%RAML 0.8 title: ExampleRAML schemas: - presentation: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "title": { "type": "string" } } } /presentations: &presentations type: { typedCollection: { schema: presentation } } get: responses: 200: body: application/json: example: | [ { "title": "Presentation Video" }, { "title": "Environment Spec Report" } ]
Using 0 or 1 as the value of an example of a Boolean
An example for a Boolean must have a value of "true" or "false". In this API specification illustrating the violation, the value of the example for the form parameter is_public
is incorrect.
#%RAML 0.8 title: ExampleRAML /upload: post: description: | Upload a photo body: multipart/form-data: formParameters: title: description: The title of the photo. is_public: type: boolean example: 1
Not including a property in an example
If an example is missing a property of the type that it is exemplifying, the editor displays this violation message:
should have required property 'property name'
For example, the property age
is missing in the example:
#%RAML 0.8 title: Example API Spec /clients: get: responses: 200: body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "properties": { "firstName": { "type": "string" }, "lastName": { "type": "string" }, "age": { "type": "number", "required": true } }, "required": false, "type": "object" } example: firstName: John lastName: Smith
Either add the property to the example or, in the type declaration, declare the property as optional.
In this case, the property is added to the example:
#%RAML 0.8 title: Example API Spec /clients: get: responses: 200: body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "properties": { "firstName": { "type": "string" }, "lastName": { "type": "string" }, "age": { "type": "number", "required": true } }, "required": false, "type": "object" } example: firstName: John lastName: Smith age: 30
In this case, the property is declared as optional:
#%RAML 0.8 title: Example API Spec /clients: get: responses: 200: body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "properties": { "firstName": { "type": "string" }, "lastName": { "type": "string" }, "age": { "type": "number", "required": false } }, "required": false, "type": "object" } example: firstName: John lastName: Smith
Not using the data type of the RAML element in the example for that element
In all cases, the data type of an example must match the data type of the element that it is an example of.
In this incorrect API specification, a query parameter is defined as a string; however, the example of the query parameter is an integer.
#%RAML 0.8 title: ExampleRAML /books: get: queryParameters: publicationYear: type: string example: 2016
Using an invalid path for a reference inside a JSON schema
When you use the $ref
keyword in a JSON schema, the path that you specify with it must start at the root of the schema. For example, the $ref
keyword used for the property input2
in the following schema uses an incorrect path to refer to the property input
.
#%RAML 0.8 title: ExampleRAML version: v1 schemas: - authCodeResponse : | { "$schema": "http://json-schema.org/draft-04/schema", "properties": { "input": { "type": "string" }, "input2": { "$ref": "input" } }, "type": "object" }
The path must start at the root level of the schema and descend through the tree structure. This example of the schema shows the same $ref
keyword using the correct path.
{ "$schema": "http://json-schema.org/draft-04/schema", "properties": { "input": { "type": "string" }, "input2": { "$ref": "#/properties/input" } }, "type": "object" }
Declaring a URI parameter that is never used
If an API specification declares a URI parameter, but then does not use that parameter, the editor displays this warning message:
unused uri parameter “parameter”
If the parameter is declared as a base URI parameter, but is not used, then this is the warning message:
unused base uri parameter “parameter”
For example, the following API specification would generate two warning messages:
unused uri parameter "unusedParam"
unused base uri parameter "unusedUriParam"
#%RAML 0.8 title: test baseUri: http://param.raml/a/{baseUriParam1}/{nonExists}/{baseUriParam2} baseUriParameters: baseUriParam1: type: string baseUriParam2: type: string unusedParam: type: string /endpoint/{uriParam1}/{nonExistsUri}: uriParameters: uriParam1: type: string unusedUriParam: type: string
To resolve the warning messages, you would simply need to remove the lines that declare these parameters:
#%RAML 0.8 title: test baseUri: http://param.raml/a/{baseUriParam1}/{nonExists}/{baseUriParam2} baseUriParameters: baseUriParam1: type: string baseUriParam2: type: string /endpoint/{uriParam1}/{nonExistsUri}: uriParameters: uriParam1: type: string
Not declaring a media type for a payload
If the declaration of a payload does not declare a media type, the editor displays this message:
Payload media type is mandatory
For example, the editor would display this message for the following API specification:
#%RAML 0.8 title: Example API Spec /media: get: responses: 200: body: type: string
There are two methods that you can choose from to resolve the problem:
-
Declare the media type locally in the payload declaration.
#%RAML 0.8 title: Example API Spec /media: get: responses: 200: body: application/json: type: string
-
Specify the default media type globally for the API specification.
#%RAML 0.8 title: Example API Spec mediaType: application/json /media: get: responses: 200: body: type: string
The following example uses both a global and a local declaration. In this case, the mediaType
node defines acceptable media types as application/json
and application/xml
. The first type, Person
, returns a body that is in either media type. However, the second type, Another
, overrides the global declaration with a local one, and returns only a JSON body.
#%RAML 0.8 title: New API mediaType: [ application/json, application/xml ] schemas: Person: Another: /list: get: responses: 200: body: Person /send: post: body: application/json: schema: Another
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 a schema that contains invalid JSON
The JSON in files that are included in the value of the schemas
property must be valid.
The first example includes the schema appSwitcher.json
. However, the second shows that there is an error in the JSON: at the end of the last value, there is a comma, though there should instead be a quotation mark.
#%RAML 0.8 title: ExampleRAML schemas: - appSwitcher: !include schemas/appSwitcher.json
{ "appMenuItems" : [ { "type" : "Tabset" , "content" : null , "icons" : null , "colors" : null , "label" : "Call Center" , "url" : "/home/home.jsp?tsid=02uxx00000056Sr" } , { "type" : "Tabset" , "content" : null , "icons" : null , "colors" : null , "label" : "Community" , "url" : "/home/home.jsp?tsid=02uxx00000056Sw" } , { "type" : "Tabset" , "content" : null , "icons" : null , "colors" : null , "label" : "App Launcher" , "url" : "/app/mgmt/applauncher/appLauncher.apexp?tsid=02uxx00000056Sx, } ] }
Using invalid JSON in examples of JSON schemas
Examples of JSON schemas must be valid, unlike the example in the following API specification:
#%RAML 0.8 title: ExampleRAML ... /api: get: responses: 200: body: application/json: schema: { "type": "object", "required": true, "$schema": "http://json-schema.org/draft-03/schema", "properties": { "a": { "type": "boolean", "required": true } } } example: { "a: { "a": "" }
Not providing a YAML map when a facet requires one
When a facet is described in the RAML 0.8 specification as requiring a map as a value, but the API specification doesn’t provide a map, the editor returns the message YAML map expected
.
Here is an example of the error:
#%RAML 0.8 title: Test version: 1.0 securitySchemes: basic: type: Basic Authentication settings:
There are two ways to fix the error.
-
Provide a map as a value.
#%RAML 0.8 title: Test version: 1.0 securitySchemes: basic: type: Basic Authentication settings: requestTokenUri: https://api.mysampleapi.com/1/oauth/request_token
-
Delete the facet — in this case,
settings
— that requires a map.#%RAML 0.8 title: Test version: 1.0 securitySchemes: basic: type: Basic Authentication
Using an unsupported property
This error occurs if you use an undefined facet.
- Example error message
-
Property invalidfacet not supported in a RAML 0.8 webApi node
, whereinvalidfacet
is the name of a facet that is not defined in the RAML specification.
Here is an example that would generate this error:
Incorrect | Correct |
---|---|
#%RAML 0.8 title: Test invalidfacet: version: |
#%RAML 0.8 title: Test version: |
Declaring an undefined type in a header
This error occurs when a non-existent type is specified in a header.
- Error message
-
Cannot declare unresolved parameter
In the incorrect example below, the value for the header myHeader
has a typo. It is specified as strang
, not as string
.
Incorrect | Correct |
---|---|
#%RAML 0.8 title: test /endpoint: post: headers: myHeader: strang |
#%RAML 0.8 title: test /endpoint: post: headers: myHeader: string |