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 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.
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.
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.
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.
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 ].
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.
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.
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.
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.
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.
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).
