Skip to content
This repository has been archived by the owner on Feb 17, 2024. It is now read-only.

Update raml-10.md #769

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Update raml-10.md #769

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ddf0993
Update raml-10.md
antoniogarrote Mar 25, 2022
eaa5b43
Update raml-10.md
antoniogarrote Mar 25, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 12 additions & 2 deletions versions/raml-10/raml-10.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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.
Expand Down