From ddf099303372f1731191125f6c569e30a26dcf04 Mon Sep 17 00:00:00 2001 From: Antonio Garrote Date: Fri, 25 Mar 2022 14:31:54 -0700 Subject: [PATCH 1/2] Update raml-10.md Making the declaration of the annotation type optional. This will allow better interoperability with OAS, where extensions are not required to have a strict schema. This also makes it possible to easily generate annotations when enriching the spec via software for automation use cases. The change is backward compatible. Users that want to provide a better experience can still provide the annotation type. --- versions/raml-10/raml-10.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index cb2d9c4..544b334 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -2958,7 +2958,7 @@ If the allowedTargets node is not present, the annotation can be applied in any ### Applying Annotations -To be applied in an API specification, the annotation MUST be declared in an annotation type. +To be applied in an API specification, the annotation SHOULD be declared in an annotation type. If no annotation type is found, the `any` RAML type would be used to validate the body of the annotation. A declared annotation can be applied to a node in the specification by adding an annotation node on that node whose key is the name of the annotation type enclosed in parentheses. The annotation value MUST be valid according to the corresponding annotation type. From eaa5b4324c2fe816e25767ec61bec540ed01a01c Mon Sep 17 00:00:00 2001 From: Antonio Garrote Date: Fri, 25 Mar 2022 14:55:38 -0700 Subject: [PATCH 2/2] Update raml-10.md Adding more details to the explanation of how annotations can be used without declaration --- versions/raml-10/raml-10.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 544b334..6fd344f 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -2896,7 +2896,7 @@ The list of required and optional parameters to be provided to the security sche Annotations provide a mechanism to extend the API specification with metadata beyond the metadata already defined in this RAML 1.0 specification. Annotations can also be used to add properties to the built-in RAML nodes in certain locations within the RAML specification. Processors MAY support certain annotations to add additional specificity to the API description, enable tooling such as testing, support API repositories and API discovery, and so on. Processors MAY ignore any and all annotations. -Annotations used in an API specification MUST be declared in a root-level annotationTypes node. Annotations can have values, which are defined and constrained in annotation type declarations. Processors can then rely on the declarations to ensure annotation values meet expectations. +Annotations used in an API specification SHOULD be declared in a root-level annotationTypes node. Annotations can have values, which are defined and constrained in annotation type declarations. Processors can then rely on the declarations to ensure annotation values meet expectations. The following example shows various annotation type declarations and the application of the annotations to an API definition. @@ -2987,6 +2987,16 @@ annotationTypes: (testHarness): usersTest ``` +This final example showcases how the annotation can be directly applied without declaration in the API specification: + +```yaml +#%RAML 1.0 +title: Testing annotations +mediaType: application/json +/users: + (testHarness): usersTest +``` + #### Annotating Scalar-valued Nodes It is often useful to annotate scalar-valued nodes, for example `baseUri`. Annotations are typically applied as extra key-value pairs to map-valued nodes that inherently accept key-value pairs. Annotations cannot be easily applied to scalar-valued nodes. To apply annotations to any scalar-valued node, a RAML processor MUST also support scalar-valued nodes expressed as a map that allow a single key `value` as an alternative to the normal syntax.