Define & Validate APIsValidation Rulesets
RAML Rulesets
The ruleset APIMatic uses to validate RAML documents.
APIMatic validates RAML documents (v0.8, v1.0) against the ruleset below. These include rules defined by the standard as well as additional checks APIMatic enforces for better output.
RAML Validation
Validation checks performed on RAML v0.8 or v1.0 files.
| Property | Value |
|---|---|
| Ruleset ID | raml-validation |
| Code prefix | RAML_V |
| Type | Validation |
| Default severity | Error |
| Rule system | Semantic |
| Rules | 25 |
Basic Structure
| Code | Rule | Severity | What it checks |
|---|---|---|---|
RAML_V001 | valid-raml-syntax | Blocking | RAML API definitions must be valid YAML 1.2-compliant documents. |
RAML_V002 | valid-json-raml | Blocking | The legacy RAML v0.8 format unofficially supports a RAML+JSON version where RAML files could be defined using JSON instead of the default YAML syntax. APIMatic also supports such files. However, they must not contain any syntax/semantic issues and should use only valid JSON. |
RAML_V003 | valid-combined-raml-yaml | Blocking | A RAML master file may reference one or more of external files (using !include) that are either available locally in a ZIP file or in a public URL. Before the information in the RAML file can be processed further, the data from the various files need to be included/merged into the master RAML file. The resulting master RAML file must contain valid YAML content. This means that individual files contributing their content to the RAML master file must also contain valid JSON/YAML/XML/Markdown content that won't render the merged RAML YAML file as invalid. |
RAML_V004 | valid-property-value-type | Blocking | Value of a RAML standard property must be in accordance with the type set by the standard for that property. |
API Metadata
| Code | Rule | Severity | What it checks |
|---|---|---|---|
RAML_V100 | required-title | Error | The root object of RAML document must specify a short user-friendly title of the API using the title property. If title information is not provided, a default value will be assigned to it automatically during import/transformations in APIMatic. |
RAML_V101 | required-base-uri | Error | The root object of RAML document must specify the URL for the target API host using the baseUri property. This will serve as the base URL for all resources in the document. If base URI information is not provided, a dummy value will be assigned automatically during import/transformations in APIMatic. |
RAML_V102 | required-base-uri-parameter-default-value | Error | A default value must be provided for the base URI parameter using the default property that can be substituted in the base URI in case no other value is supplied at the time of making the request. If a value is not provided in the RAML document, a dummy value will be assigned automatically as the default value during import/transformations in APIMatic. |
Types
| Code | Rule | Severity | What it checks |
|---|---|---|---|
RAML_V200 | valid-raml-08-schema-definition | Error | Each schema definition provided in the root object schemas list must be a valid JSON schema string, XML schema string or an external path to one of these using the !include keyword. |
RAML_V201 | raml-1-0-schemas-and-types-are-mutually-exclusive | Error | The properties schemas and types in a RAML root object are mutually exclusive. This means that in a root object instance, only one of these properties must be present at a time but not both. It is recommended to use the types property because a future RAML version might remove the schemas alias with that property. |
RAML_V202 | valid-type-declaration-type | Error | The value of a type node must either be the name of a user-defined type, the name of a built-in RAML data type (object, array, or one of the scalar types) or an inline type declaration. |
RAML_V203 | type-declaration-type-and-schema-are-mutually-exclusive | Error | The properties schema and type in a type declaration are mutually exclusive. This means that in a type declaration, only one of these properties must be present at a time but not both. It is recommended to use the type property because a future RAML version might remove the schema alias with that property. |
RAML_V204 | type-declaration-example-and-examples-are-mutually-exclusive | Error | The properties example and examples in a type declaration are mutually exclusive. This means that in a type declaration, only one of these properties must be present at a time but not both. |
RAML_V205 | no-cyclic-dependency-in-type-declaration | Error | In RAML, custom types can be defined by extending the built-in or named types and then used like built-in types. Extending types must not create any cyclic dependencies. |
RAML_V206 | common-base-type-of-multiple-inheritance-types | Error | When multiple inheritance is used i.e. a sequence of types are passed to the type property, all types involved must have a common base/primitive type. This means that it is not allowed to inherit from different kind of primitive types, for example [ number, string ]. |
Resources and Methods
| Code | Rule | Severity | What it checks |
|---|---|---|---|
RAML_V400 | get-method-cannot-have-body | Warning | If a resource defines a get method, the method must not define a body section as such methods do not expect a body and, therefore, all related information will be ignored automatically during import/transformations in APIMatic. |
RAML_V401 | supported-response-status-code | Warning | If multiple responses are disabled via import settings provided in the APIMatic Metadata file, only method response definitions belonging to status code ranges 200-208 and 400-599 will be imported. Those outside the supported range will be ignored automatically during import/transformations in APIMatic. |
Resource Types and Traits
| Code | Rule | Severity | What it checks |
|---|---|---|---|
RAML_V500 | valid-resource-type-name | Error | A resource may specify the resource type from which it is derived using the optional type property. The value must be the name of a resource type defined within the root-level resourceTypes object or in a library. |
RAML_V501 | valid-trait-name | Error | A method can specify one or more traits it inherits by using the optional is property. Each element in the is list must be the name of a trait defined within the root-level traits property or in a library. A trait can also be applied to a resource by using the is property. |
Security Schemes
| Code | Rule | Severity | What it checks |
|---|---|---|---|
RAML_V600 | required-authorization-uri-oauth2-security-scheme-setting | Error | If the OAuth 2.0 settings include implicit or authorization_code in the authorizationGrants list, the settings must also specify a non-empty authorization URL using the authorizationUri property. |
RAML_V601 | required-access-token-uri-oauth2-security-scheme-setting | Error | If the OAuth 2.0 settings include client_credentials, password or authorization_code in the authorizationGrants list, the settings must also specify a non-empty access token URL using the accessTokenUri property. |
Includes
| Code | Rule | Severity | What it checks |
|---|---|---|---|
RAML_V700 | resolvable-include-path | Error | Content of external files can be marked for inclusion in a RAML file using the !include keyword followed by a valid resolvable path to the file. The path can be a absolute path (A path that begins with a single slash (/) and is interpreted relative to the root RAML file location.), relative path (A path that neither begins with a single slash (/) nor constitutes a URL, and is interpreted relative to the location of the included file.) or an absolute URL. |
Libraries
| Code | Rule | Severity | What it checks |
|---|---|---|---|
RAML_V800 | required-library-path | Error | When root level uses property declares a list of libraries as key-value pairs, the key is treated as the library name of namespace and the value must be a path to a RAML library file, usually an external RAML library fragment document. This path must be valid and a non-empty string. |
RAML_V801 | resolvable-library-path | Error | When root level uses property declares a list of libraries as key-value pairs, the key is treated as the library name of namespace and the value must be the location of a RAML library file, usually an external RAML library fragment document. This location must be valid and accessible. Unlike includes, the path to the library document must not start with !include. The location can be a absolute path (A path that begins with a single slash (/) and is interpreted relative to the root RAML file location.), relative path (A path that neither begins with a single slash (/) nor constitutes a URL, and is interpreted relative to the location of the included file.) or an absolute URL. |
RAML_V802 | resolvable-library-reference | Error | A RAML document can reference assets from within a library using dot notation as follows: concatenate the library name followed by a period (.), followed by the name of the data type, resource type, trait, security scheme, or annotation type. For this reference to be resolvable following conditions must be satisfied: the library name must match exactly with the name of a library declared in the uses root level property, the library referenced must be accessible i.e. the path provided for the library in the uses property must be valid, and the name of the referenced asset must match exactly with the asset defined in the library. |
RAML_V803 | no-library-cyclic-dependency | Error | A library fragment document can use uses property to reference external libraries if the assets defined in the current library require external assets as well. However, the uses property in a library fragment document must not be used to reference the library itself (whether directly or indirectly). |