This is a technical document, this information is intended for experienced users
Within the Async specification it is possible to use RAML data types to define a payload, taking into account that the schema format is specified accordingly. Both specifications have their own distinct referencing and modularization mechanisms, and it is not clear where to draw the line to determine where one specification stops, and the other one starts. This document will describe how to use RAML types in Async when using AMF.
Referencing external RAML content using
In order to support referencing RAML content in external files, AMF allows the use of the
$ref mechanism present in Async.
This enables referencing data type fragments, data types present in libraries, as well as any RAML content present in yaml or json files.
However, the usage of
$ref in this scenario has some restrictions. Given that the payload content must comply with RAML,
$ref may only be used at the root of the payload definition as an exception to the RAML specification.
Its target content must be valid structurally according to the relevant RAML specification:
The following section shows all supported use cases when using this referencing mechanism, adding additional comments if necessary.
The data type fragment must be self-contained, meaning it cannot depend on any definition made in the root API. The following example is valid for this use case.
The following referenced data type is invalid as it is not self-contained, meaning the data type fragment depends on type definitions which will not be resolved in the root API.
Due to known limitations this API will not return any validations (error or warning), but the reference to the type
Other inside the data type will not be made, leaving it unresolved.
Use of relative pointers to nested content within the data type fragment is not supported, like in the following invalid example:
For the case of libraries, type definitions can be referenced using the following fixed pointer:
When referencing types defined in a library, the included content will have context of other type definitions present in the original library.
This can be seen in the following valid example where the type User references another type present in the external library.
The external library must be self-contained, meaning it cannot depend on types defined in the root API. In the following invalid example, the library depends on the definition of the type Other, which will not be resolved from the definitions present in the main API.
When referencing external yaml or json files, the
$ref inlines the content.
Relative json pointers can be used to reference content that is nested within the file, but taking into account the following limitation:
When referencing to external yaml/json files
the external file must not be a known RAML fragment or API specification.
The following case is a valid reference making use of relative json pointers.
As previously mentioned, when the target file is a known RAML fragment or API specification free use of relative json pointers is not supported. The following example shows an invalid example when using relative json pointer to reference an external RAML specification:
The simplest way to define a RAML type in Async is by defining your content inlined under the
payload facet while using the appropriate schema format like so:
All content within the payload will be considered strictly RAML, except when using ‘$ref’ at the root of the payload (see the previous section for more details).
When defining inlined types, its context is fully restricted from the content defined outside the payload facet.
This means that any reference to content defined in the
components facet of the main Async API will not be resolved.
RAML has its own referencing mechanism to include content from external files using a reserved yaml tag
AMF will only support referencing external data type fragments using the
Furthermore, this will only work in Async APIs defined in yaml format, as json has no way of defining tags.
As this syntax is valid within a RAML context, including data types fragments can be made at the root of the payload content, or nested within other inlined content: