> is required
+/servers:
+ get:
+ is: [ { secured : { tokenName: token } } ]
+```
+
+To resolve a collision arising from this inequality, priority is given to the trait in closest proximity to the target method or resource. In the previous example, the `tokenName` parameter value for the `GET:/servers` method is `token`, and the trait list consists of single trait occurrence: `[ {secured:{ tokenName:token}} ]`.
+
+## Security Schemes
+
+Most REST APIs have one or more mechanisms to secure data access, identify requests, and determine access level and data visibility.
+
+This section describes how an API designer MAY include security scheme definitions in RAML API definitions. This section also outlines the support documentation that the client and server implementation generators SHOULD include.
+
+### Security Scheme Types
+
+RAML supports the following built-in security scheme types:
+
+|Type |Description|
+|:----------|:----------|
+|OAuth 1.0 | The API authentication requires using OAuth 1.0 as described in [RFC5849](https://tools.ietf.org/html/rfc5849)
+|OAuth 2.0 | The API authentication requires using OAuth 2.0 as described in [RFC6749](https://tools.ietf.org/html/rfc6749)
+|Basic Authentication| The API authentication relies on using Basic Access Authentication as described in [RFC2617](https://tools.ietf.org/html/rfc2617)
+|Digest Authentication| The API authentication relies on using Digest Access Authentication as described in [RFC2617](https://tools.ietf.org/html/rfc2617)
+|Pass Through| Headers or query parameters are passed through to the API based on a defined mapping.
+|x-{other}| The API authentication relies on another authentication method.
+
+A processing application developer MAY provide support for these mechanisms. If a mechanism is supported, it MUST conform to the specified standard.
+
+Additionally, any security scheme definition may be augmented with a describedBy node, which allows the designer to document the API security scheme.
+
+### Security Scheme Declaration
+
+The security scheme node is a map that has the following key-value pairs:
+
+|Name |Description|
+|:----------|:----------|
+| type | Specifies the API security mechanisms. One API-supported authentication method is allowed. The value MUST be one of the following methods: OAuth 1.0, OAuth 2.0, Basic Authentication, Digest Authentication, Pass Through, x-<other>
+| displayName? | An alternate, human-friendly name for the security scheme.
+| description? | Information that MAY be used to describe a security scheme. Its value is a string and MAY be formatted using [markdown](#markdown).
+| [describedBy?](#describedby) | A description of the following security-related request components determined by the scheme: the headers, query parameters, or responses. As a best practice, even for standard security schemes, API designers SHOULD describe these nodes of security schemes. Including the security scheme description completes the API documentation.
+| settings? | The [settings](#settings) attribute MAY be used to provide security scheme-specific information.
+
+An optional **securitySchemes** node is defined for the RAML document root. The value of securitySchemes is a map having key-value pairs that map security scheme names to security scheme declarations.
+
+Each authentication pattern supported by the API must be expressed as a component of the **securitySchemes** node value.
+
+In this example, the Dropbox API supports authentication using OAuth 2.0 and OAuth 1.0:
+
+```yaml
+#%RAML 1.0
+title: Dropbox API
+version: 1
+baseUri: https://api.dropbox.com/{version}
+securitySchemes:
+ oauth_2_0:
+ description: |
+ Dropbox supports OAuth 2.0 for authenticating all API requests.
+ type: OAuth 2.0
+ describedBy:
+ headers:
+ Authorization:
+ description: |
+ Used to send a valid OAuth 2 access token. Do not use
+ with the "access_token" query string parameter.
+ type: string
+ queryParameters:
+ access_token:
+ description: |
+ Used to send a valid OAuth 2 access token. Do not use with
+ the "Authorization" header.
+ type: string
+ responses:
+ 401:
+ description: |
+ Bad or expired token. This can happen if the user or Dropbox
+ revoked or expired an access token. To fix, re-authenticate
+ the user.
+ 403:
+ description: |
+ Bad OAuth request (wrong consumer key, bad nonce, expired
+ timestamp...). Unfortunately, re-authenticating the user won't help here.
+ settings:
+ authorizationUri: https://www.dropbox.com/1/oauth2/authorize
+ accessTokenUri: https://api.dropbox.com/1/oauth2/token
+ authorizationGrants: [ authorization_code, refresh_token ]
+ oauth_1_0:
+ description: |
+ OAuth 1.0 continues to be supported for all API requests, but OAuth 2.0 is now preferred.
+ type: OAuth 1.0
+ settings:
+ requestTokenUri: https://api.dropbox.com/1/oauth/request_token
+ authorizationUri: https://www.dropbox.com/1/oauth/authorize
+ tokenCredentialsUri: https://api.dropbox.com/1/oauth/access_token
+```
+
+#### describedBy
+
+The value of the **describedBy** node is defined as a map with the following key-value pairs as follows:
+
+|Name |Description|
+|:----------|:----------|
+| headers? | Optional array of [Headers](#headers), documenting the possible headers that could be accepted.
+| queryParameters? | Query parameters, used by the schema to authorize the request. Mutually exclusive with [queryString](#query-strings-and-query-parameters).
+| queryString? | The query string used by the schema to authorize the request. Mutually exclusive with [queryParameters](#query-strings-and-query-parameters).
+| responses? | An optional array of [responses](#responses), representing the possible responses that could be sent.
+| (<annotationName>)? | [Annotations](#annotations) to be applied to this API. An annotation is a map having a key that begins with "(" and ends with ")" where the text enclosed in parentheses is the annotation name, and the value is an instance of that annotation.
+
+#### Settings
+
+The **settings** node MAY be used to provide security scheme-specific information. The required nodes vary depending on which type of security scheme is declared.
+
+The settings node describes the minimum set of properties that any processing application MUST provide and validate if it chooses to implement the security scheme. Processing applications MAY choose to recognize other properties for token lifetime, preferred cryptographic algorithms, and other things.
+
+##### OAuth 1.0
+
+Security schemes of this type have the following nodes:
+
+|Name |Description |
+|:--------|:------------|
+| requestTokenUri | The URI of the *Temporary Credential Request endpoint* as defined in [RFC5849 Section 2.1](https://tools.ietf.org/html/rfc5849#section-2.1)
+| authorizationUri | The URI of the *Resource Owner Authorization endpoint* as defined in [RFC5849 Section 2.2](https://tools.ietf.org/html/rfc5849#section-2.2)
+| tokenCredentialsUri | The URI of the *Token Request endpoint* as defined in [RFC5849 Section 2.3](https://tools.ietf.org/html/rfc5849#section-2.3)
+| signatures | A list of signature methods used by the Authorization server, which can be any of the following: `HMAC-SHA1`, `RSA-SHA1`, or `PLAINTEXT`. If signatures is missing, it is assumed that the Authentication server allows any signature method defined in [RFC5849 Section 3.4](https://tools.ietf.org/html/rfc5849#section-3.4).
+
+OAuth 1.0 authentication follows the standard described in [RFC5849](https://tools.ietf.org/html/rfc5849). The following example shows how to set OAuth 1.0 properties:
+
+```yaml
+#%RAML 1.0
+title: My Sample API
+securitySchemes:
+ oauth_1_0:
+ description:|
+ OAuth 1.0 continues to be supported for all API requests, but OAuth 2.0 is now preferred.
+ type: OAuth 1.0
+ settings:
+ requestTokenUri: https://api.mysampleapi.com/1/oauth/request_token
+ authorizationUri: https://api.mysampleapi.com/1/oauth/authorize
+ tokenCredentialsUri: https://api.mysampleapi.com/1/oauth/access_token
+ signatures: [ 'HMAC-SHA1', 'PLAINTEXT' ]
+```
+
+##### OAuth 2.0
+
+Security schemes of this type have the following nodes:
+
+| Name |Description |
+|:--------|:------------|
+|authorizationUri| The URI of the *Authorization Endpoint* as defined in [RFC6749 Section 3.1](https://tools.ietf.org/html/rfc6749#section-3.1). Providing an Authorization Endpoint is only mandatory using either the `authorization_code` or `implicit` grant type. It is not mandatory for any other.
+|accessTokenUri| The URI of the *Token Endpoint* as defined in [RFC6749 Section 3.2](https://tools.ietf.org/html/rfc6749#section-3.2).
+|authorizationGrants| A list of the authorization grants supported by the API as defined in RFC6749 Sections [4.1](https://tools.ietf.org/html/rfc6749#section-4.1), [4.2](https://tools.ietf.org/html/rfc6749#section-4.2), [4.3](https://tools.ietf.org/html/rfc6749#section-4.3) and [4.4](https://tools.ietf.org/html/rfc6749#section-4.4), which can be either any of the following grants: `authorization_code`, `password`, `client_credentials`, or `implicit`; or any absolute URI as defined in section [4.5](defined in https://tools.ietf.org/html/rfc6749#section-4.5).
+|scopes| A list of scopes supported by the API as defined in [RFC6749 Section 3.3](https://tools.ietf.org/html/rfc6749#section-3.3)
+
+OAuth 2.0 authentication follows the standard described in [RFC6749](https://tools.ietf.org/html/rfc6749). The following example shows how to set OAuth 2.0 properties:
+
+```yaml
+#%RAML 1.0
+title: Dropbox API
+version: 1
+baseUri: https://api.dropbox.com/{version}
+securitySchemes:
+ oauth_2_0:
+ description: |
+ Dropbox supports OAuth 2.0 for authenticating all API requests.
+ type: OAuth 2.0
+ describedBy:
+ headers:
+ Authorization:
+ description: |
+ Used to send a valid OAuth 2 access token. Do not use
+ with the "access_token" query string parameter.
+ type: string
+ queryParameters:
+ access_token:
+ description: |
+ Used to send a valid OAuth 2 access token. Do not use with
+ the "Authorization" header.
+ type: string
+ responses:
+ 401:
+ description: |
+ Bad or expired token. This can happen if the user or Dropbox
+ revoked or expired an access token. To fix, re-authenticate
+ the user.
+ 403:
+ description: |
+ Bad OAuth request (wrong consumer key, bad nonce, expired
+ timestamp...). Unfortunately, re-authenticating the user won't help here.
+ settings:
+ authorizationUri: https://www.dropbox.com/1/oauth2/authorize
+ accessTokenUri: https://api.dropbox.com/1/oauth2/token
+ authorizationGrants: [ authorization_code, refresh_token, 'urn:ietf:params:oauth:grant-type:saml2-bearer' ]
+```
+
+##### Basic Authentication
+
+Note: Basic security does not require any further specification of settings in the API Definition.
+
+```yaml
+#%RAML 1.0
+title: Dropbox API
+version: 1
+baseUri: https://api.dropbox.com/{version}
+securitySchemes:
+ basic:
+ description: |
+ This API supports Basic Authentication.
+ type: Basic Authentication
+```
+
+##### Digest Authentication
+
+Note: Digest security does not require any further specification of settings in the API Definition.
+
+```yaml
+#%RAML 1.0
+title: Dropbox API
+version: 1
+baseUri: https://api.dropbox.com/{version}
+securitySchemes:
+ digest:
+ description: |
+ This API supports DigestSecurityScheme Authentication.
+ type: Digest Authentication
+```
+
+##### Pass Through
+
+Pass through authentication does not have any specific settings defined and the implementation is known to RAML. You MUST provide a value for every header or queryParameter defined in describedBy and passed along with the request without modification. The following example shows how to provide these values:
+
+```yaml
+#%RAML 1.0
+title: Dropbox API
+version: 1
+baseUri: https://api.dropbox.com/{version}
+securitySchemes:
+ passthrough:
+ description: |
+ This API supports Pass Through Authentication.
+ type: Pass Through
+ describedBy:
+ queryParameters:
+ query:
+ type: string
+ headers:
+ api_key:
+ type: string
+```
+
+##### x-<other>
+
+x-<other> authentication methods do not have any specific settings defined, as the implementation of these methods is unknown as a standard to RAML. These security schemes might include only the description and describedBy sections to allow documentation of the intended use of the security scheme. The following example shows such a security scheme:
+
+```yaml
+#%RAML 1.0
+title: Custom API
+version: 1
+baseUri: https://api.custom.com/{version}
+securitySchemes:
+ custom_scheme:
+ description: |
+ A custom security scheme for authenticating requests.
+ type: x-custom
+ describedBy:
+ headers:
+ SpecialToken:
+ description: |
+ Used to send a custom token.
+ type: string
+ responses:
+ 401:
+ description: |
+ Bad token.
+ 403:
+```
+
+#### Applying Security Schemes
+
+The **securedBy** node in the RAML document root can apply security schemes to every method of the API. All API methods, except those having their own securedBy node, can be authenticated by any of the specified security schemes.
+
+Applying a security scheme to a method overrides any security scheme applied to the API as a whole. To indicate that a method is protected using a specific security scheme, the method MUST be defined by using the **securedBy** node.
+
+The value assigned to the securedBy node MUST be a list of any of the security schemes previously defined in the **securitySchemes** node of RAML document root.
+
+```yaml
+#%RAML 1.0
+title: Dropbox API
+version: 1
+baseUri: https://api.dropbox.com/{version}
+securedBy: [oauth_2_0]
+securitySchemes:
+ oauth_2_0: !include securitySchemes/oauth_2_0.raml
+ oauth_1_0: !include securitySchemes/oauth_1_0.raml
+/users:
+ get:
+ securedBy: [oauth_2_0, oauth_1_0]
+```
+
+A securedBy node containing null as the array component indicates the method can be called without applying any security scheme.
+
+```yaml
+#%RAML 1.0
+title: GitHub API
+version: v3
+baseUri: https://api.github.com
+securitySchemes:
+ oauth_2_0: !include securitySchemes/oauth_2_0.raml
+/users/{userid}/gists:
+ get:
+ securedBy: [null, oauth_2_0]
+```
+
+The **securedBy** node can also apply a list of security schemes to a resource. All resource methods, except those having their own securedBy node, can be authenticated by any of the specified security schemes. The value of the resources node overrides that of the root attribute. Security schemes applied to a resource MUST NOT incorporate nested resources; security schemes do not apply to existing nested resources.
+
+Applying a security scheme to a method overrides security schemes applied to the API and to resources having the method as a sibling.
+
+If the processing application supports custom nodes, custom parameters can be provided to the security scheme at the moment of inclusion in a method.
+
+The following example assigns a value to the parameter **scopes**:
+
+```yaml
+#%RAML 1.0
+title: GitHub API
+version: v3
+baseUri: https://api.github.com
+securitySchemes:
+ oauth_2_0: !include securitySchemes/oauth_2_0.raml
+/users/{userid}/gists:
+ get:
+ securedBy: [null, oauth_2_0: { scopes: [ ADMINISTRATOR ] } ]
+```
+
+The list of required and optional parameters to be provided to the security scheme is specified by the security scheme type.
+
+## Annotations
+
+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.
+
+The following example shows various annotation type declarations and the application of the annotations to an API definition.
+
+```yaml
+#%RAML 1.0
+title: Illustrating annotations
+mediaType: application/json
+annotationTypes:
+ deprecated: null
+ experimental: null | string
+ feedbackRequested: string?
+ testHarness:
+ type: string # This line can be omitted as it's the default type
+ badge: # This annotation type allows string values, too
+ clearanceLevel:
+ properties:
+ level:
+ enum: [ low, medium, high ]
+ required: true
+ signature:
+ pattern: "\\d{3}-\\w{12}"
+ required: true
+/groups:
+ (experimental):
+ (feedbackRequested):
+/users:
+ (testHarness): usersTest
+ (badge): tested.gif
+ (clearanceLevel):
+ level: high
+ signature: 230-ghtwvfrs1itr
+ get:
+ (deprecated):
+ (experimental):
+ (feedbackRequested): Feedback committed!
+ responses:
+ 200:
+```
+
+Annotations applied to a data type are not inherited when that data type is inherited. However, processors SHOULD make the information about the annotations in the data type hierarchy available. Annotations applied to, or within, a resource type or trait are also applied to the resource type, resource, or method that inherits the resource type or trait. In particular, if a trait is applied to a resource type or resource, all annotations on or within that trait are applied implicitly to all methods of that resource. If the inheriting resource type, resource, or method explicitly applies an annotation of a given type, then this annotation overrides all applications of that annotation type which would otherwise have been inherited and implicitly applied. In particular, if a trait is applied to a resource type or resource, and the resource type or resource applies an annotation of some type, then any and all applications of annotations of that type to that trait are overridden.
+
+### Declaring Annotation Types
+
+Annotation types are declared using the OPTIONAL root-level **annotationTypes** node. The value of the annotationsType node is a map whose keys define annotation type names, also referred to as annotations, and whose values are key-value pairs called annotation type declarations. An annotation type declaration has the same syntax as a data type declaration, and its facets have the same syntax as the corresponding ones for data types, but with the addition of the allowedTargets facet. An annotation type declaration constrains the value of an annotation of that type just as a data type declaration constrains the value of a URI parameter, query parameter, header, or body of that type. The allowedTargets node restricts the kinds of locations where the annotation can be applied. Annotation types, like data types, can extend other data types, but annotation types themselves can neither be extended nor used anywhere data types can be used.
+
+|Name |Description |
+|:--------|:------------|
+| displayName? | A friendly name used only for display or documentation purposes. The default is the element key, the name of the annotation itself.
+| description? | The intended use or meaning of an annotation. A string that MAY be formatted using [markdown](#markdown).
+| (<annotationName>)? | [Annotations](#annotations) to be applied to this API. An annotation is a map having a key that begins with "(" and ends with ")" where the text enclosed in parentheses is the annotation name, and the value is an instance of that annotation.
+| allowedTargets? | The locations to which annotations are restricted. If this node is specified, annotations of this type may be applied only on a node corresponding to one of the locations. The value MUST be one or more of the options described in the [Target Locations](#annotation-target-location).
+
+If an annotation type declaration specifies neither a type facet nor a properties facet, the default annotationName type is string.
+
+All annotations used in an API specification MUST be declared in its annotationTypes node. Any value of an annotation MUST be valid according to its annotation type.
+
+If the allowedTargets node is not present, the annotation can be applied in any of the target locations listed in the Target Locations table. If the allowedTargets node is present, it restricts where the annotation can be applied, as described in [Annotation Targets](#annotation-targets).
+
+
+### Applying Annotations
+
+To be applied in an API specification, the annotation MUST be declared in an annotation type.
+
+A declared annotation can be applied to a node in the specification by adding an annotation node on that whose key is the name of the annotation type enclosed in parentheses. The annotation value MUST be valid according to the corresponding annotation type.
+
+The example below, a small subset of the previous example, shows an explicit declaration and use of a testHarness annotation that should be a string value.
+
+```yaml
+#%RAML 1.0
+title: Testing annotations
+mediaType: application/json
+annotationTypes:
+ testHarness:
+ type: string
+/users:
+ (testHarness): usersTest
+```
+
+The following example is semantically equivalent to the previous one, but relies on the implicit, default declaration of the value type when there is no explicit type declaration.
+
+```yaml
+#%RAML 1.0
+title: Testing annotations
+mediaType: application/json
+annotationTypes:
+ testHarness:
+/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.
+
+The following example shows a scalar-valued node which is normally expressed as:
+
+```yaml
+baseUri: http://www.example.com/api
+```
+
+The alternative map syntax with `value` as the key is added to the example:
+
+```yaml
+baseUri:
+ value: http://www.example.com/api
+```
+
+Now, annotations can be applied normally, as shown in this example:
+
+```yaml
+baseUri:
+ value: http://www.example.com/api
+ (redirectable): true
+```
+
+The following list shows all available scalar-valued nodes supported in RAML:
+
+```
+displayName
+description
+type
+schema
+default
+example
+usage
+repeat
+required
+content
+strict
+minLength
+maxLength
+uniqueItems
+minItems
+maxItems
+discriminator
+minProperties
+maxProperties
+discriminatorValue
+pattern
+format
+minimum
+maximum
+multipleOf
+requestTokenUri
+authorizationUri
+tokenCredentialsUri
+accessTokenUri
+title
+version
+baseUri
+mediaType
+extends
+```
+
+#### Annotation Targets
+
+The location within an API specification where annotations can be applied MUST be one of the target locations in the following Target Locations table. The targets are the locations themselves, not sub-properties within the locations; for example, the Method target refers to the method node, not to the method display name, description, and so on.
+
+
+
+**Target Locations**
+
+|Target | Description |
+|:--------|:------------|
+| API | The root of a RAML document
+| DocumentationItem | An item in the collection of items that is the value of the root-level documentation node
+| Resource | A resource (relative URI) node, root-level or nested
+| Method | A method node
+| Response | A declaration of the responses node, whose key is an HTTP status code
+| RequestBody | The body node of a method
+| ResponseBody | The body node of a response
+| TypeDeclaration | A data type declaration (inline or in a global types collection), header declaration, query parameter declaration, URI parameter declaration, or a property within any of these declarations, where the type property can be used
+| Example | Either an example or examples node
+| ResourceType | A resource type node
+| Trait | A trait node
+| SecurityScheme | A security scheme declaration
+| SecuritySchemeSettings | The settings node of a security scheme declaration
+| AnnotationType | A declaration of the annotationTypes node, whose key is a name of an annotation type and whose value describes the annotation
+| Library | The root of a library
+| Overlay | The root of an overlay
+| Extension | The root of an extension
+
+The following example illustrates applying some restrictions on the allowed targets of annotations.
+
+```yaml
+#%RAML 1.0
+title: Illustrating allowed targets
+mediaType: application/json
+annotationTypes:
+ meta-resource-method:
+ allowedTargets: [ Resource, Method ]
+ meta-data:
+ allowedTargets: TypeDeclaration
+types:
+ User:
+ type: object
+ (meta-data): on an object; on a data type declaration
+ properties:
+ name:
+ type: string
+ (meta-data): on a string property
+/users:
+ (meta-resource-method): on a resource
+ get:
+ (meta-resource-method): on a method
+ responses:
+ 200:
+ body:
+ type: User[]
+ (meta-data): on a body
+```
+
+## Modularization
+
+RAML provides several mechanisms to help modularize the ecosystem of an API specification:
+* Includes
+* Libraries
+* Overlays
+* Extensions
+
+### Includes
+
+RAML processors MUST support the OPTIONAL **!include** tag, which specifies the inclusion of external files into the API specification. Being a YAML tag, the exclamation point ("!") prefix is required. In an API specification, the !include tag is located only in a node value position. The !include tag MUST be the value of a node, which assigns the contents of the file named by the !include tag to the value of the node.
+
+In the following example, the set of types to be used in the API specification is retrieved from a file called myTypes.raml and used as the value of the types node.
+
+```yaml
+#%RAML 1.0
+title: My API with Types
+types: !include myTypes.raml
+```
+
+The !include tag accepts a single argument, the location of the content to be included, that MUST be specified explicitly. The value of the argument MUST be a path or URL as described in the following table:
+
+|Argument | Description | Examples |
+|:--------|:------------|:---------|
+| absolute path | A path that begins with a single slash ("/") and is interpreted relative to the root RAML file location. | /traits/pageable.raml
+| 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. | description.md
../traits/pageable.raml
+| URL | An absolute URL | http://dev.domain.com/api/patterns/traits.raml
+
+To simplify the API definition, and because the parsing context of the included file is not shared between the file and its parent, an included file SHALL NOT use a YAML reference to an anchor in a separate file. Likewise, a reference made from a parent file SHALL NOT reference an anchor defined in an included file.
+
+The !include tag argument must be static: namely, it MUST NOT contain any resource type parameters or trait parameters.
+
+#### Typed Fragments
+
+A file to be included MAY begin with a RAML fragment identifier line, which consists of the text _#%RAML_ followed left-to-right by a single space, the text 1.0, a single space, and one of the following fragment identifiers:
+
+|Fragment Identifier | Description | Relevant RAML Specification Section |
+|:-------------------|:------------| :-----------------------------------|
+| DocumentationItem | An item in the collection of items that is the value of the root-level documentation node | [User Documentation](#user-documentation)
+| DataType | A data type declaration where the type node may be used | [Types](#types)
+| NamedExample | A declaration of the examples facet, whose key is a name of an example and whose value describes the example | [Examples](#defining-examples-in-raml)
+| ResourceType | A single resource type declaration | [Resource Types and Traits](#resource-types-and-traits)
+| Trait | A single trait declaration | [Resource Types and Traits](#resource-types-and-traits)
+| AnnotationTypeDeclaration | A single annotation type declaration | [Annotations](#annotations)
+| Library | A RAML library | [Libraries](#libraries)
+| Overlay | An overlay file | [Overlays](#overlays)
+| Extension | An extension file | [Extensions](#extensions)
+| SecurityScheme | A definition of a security scheme | [Security Schemes](#security-schemes)
+
+If a file begins with a RAML fragment identifier line, and the fragment identifier is not Library, Overlay, or Extension, the contents of the file after removal of the RAML fragment identifier line MUST be valid structurally according to the relevant RAML specification. For example, a RAML file beginning with `#%RAML 1.0 Trait` must have the structure of a RAML trait declaration as defined in the [Resource Types and Traits](#resource-types-and-traits) section. Including the file in a correct location for a trait declaration results in a valid RAML file.
+
+The following example shows a RAML fragment file that defines a resource type and a file that includes this fragment file.
+
+```yaml
+#%RAML 1.0 ResourceType
+
+#This file is located at resourceTypes/collection.raml
+
+description: A collection resource
+usage: Use this to describe a resource that lists items
+get:
+ description: Retrieve all items
+post:
+ description: Add an item
+ responses:
+ 201:
+ headers:
+ Location:
+```
+
+```yaml
+#%RAML 1.0
+title: Products API
+resourceTypes:
+ collection: !include resourceTypes/collection.raml
+/products:
+ type: collection
+ description: All products
+
+```
+
+The resulting API definition is equivalent to the following single document:
+
+```yaml
+#%RAML 1.0
+title: Products API
+resourceTypes:
+ collection:
+ description: A collection resource
+ usage: Use this to describe a resource that lists items
+ get:
+ description: Retrieve all items
+ post:
+ description: Add an item
+ responses:
+ 201:
+ headers:
+ Location:
+/products:
+ type: collection
+ description: All products
+```
+
+#### Resolving Includes
+
+When RAML or YAML files are included, RAML parsers MUST not only read the content, but must also parse it and add the content to the declaring structure as if the content were declared inline. RAML parsers MUST parse the content of the file as RAML content and append the parsed structures to the RAML document node if the included file has a .raml, .yml, or .yaml extension or one of the following media types:
+
+* application/raml+yaml
+* text/yaml
+* text/x-yaml
+* application/yaml
+* application/x-yaml
+
+Otherwise, if RAML parsers fail to parse the content and append structures, the contents of the file are included as a scalar.
+
+Because the parsing context of the included files is not shared between the included file and its parent, an included file SHALL NOT use a YAML reference to an anchor in a separate file. Likewise, a reference made from a parent file SHALL NOT reference a structure anchor defined in an included file. These rules simplify RAML definitions.
+
+In the example below, the API root document includes two files from the patterns folder, one containing resource type declarations and the other containing trait declarations.
+
+```yaml
+#%RAML 1.0
+title: Example API
+version: v1
+resourceTypes: !include patterns/resourceTypes.raml
+traits: !include patterns/traits.raml
+```
+
+```yaml
+#%RAML 1.0
+# This file is located at patterns/resourceTypes.raml
+
+collection:
+ get:
+ is: paged
+ post:
+member:
+ get:
+ patch:
+ delete:
+```
+
+```yaml
+#%RAML 1.0
+# This file is located at patterns/traits.raml
+
+chargeable:
+ headers:
+ dept_code:
+paged:
+ queryParameters:
+ start:
+ type: number
+```
+
+The resulting API definition is equivalent to the following single document.
+
+```yaml
+#%RAML 1.0
+title: Example API
+version: v1
+resourceTypes:
+ collection:
+ get:
+ is: paged
+ post:
+ member:
+ get:
+ patch:
+ delete:
+traits:
+ chargeable:
+ headers:
+ dept_code:
+ paged:
+ queryParameters:
+ start:
+ type: number
+```
+
+### Libraries
+
+RAML libraries are used to combine any collection of data type declarations, resource type declarations, trait declarations, and security scheme declarations into modular, externalized, reusable groups. While libraries are intended to define common declarations in external documents, which are then included where needed, libraries can also be defined inline.
+
+The following table describes the nodes, which are optional, of a library node.
+
+|Name | Description |
+|:--------|:------------|
+| types?
schemas?
resourceTypes?
traits?
securitySchemes?
annotationTypes?
(<annotationName>)?
uses? | The definition of each node is the same as that of the corresponding node at the root of a RAML document. A library supports annotation node like any other RAML document.
+| usage | Describes the content or purpose of a specific library. The value is a string and MAY be formatted using [markdown](#markdown).
+
+The following example shows a simple library as a standalone, reusable RAML fragment document.
+
+```yaml
+#%RAML 1.0 Library
+usage: |
+ Use to define some basic file-related constructs.
+types:
+ File:
+ properties:
+ name:
+ length:
+ type: integer
+traits:
+ drm:
+ headers:
+ drm-key:
+resourceTypes:
+ file:
+ get:
+ is: [ drm ]
+ put:
+ is: [ drm ]
+```
+
+#### Applying Libraries
+
+Any number of libraries can be applied by using the OPTIONAL **uses** node ONLY at the root of a ["master"] RAML or RAML fragment file. The value of the uses node is a map of key-value pairs. The keys are treated as library names, or namespaces, and the value MUST be the location of a RAML library file, usually an external RAML library fragment document.
+
+In the document that applies a library, the data types, resource types, traits, security schemes, and annotation types in the library become available from the document. The assets in the library are referenced from the document using dot notation as follows: concatenate the library name followed by a period ("."), and then the name of the data type, resource type, trait, security scheme, or annotation type. The library name defines a namespace for the library nodes within the context that the library is applied. Namespaces defined in a **uses** statement in a specific file are only consumable within that file and serve only to disambiguate the included libraries from each other. Therefore, any processor MUST not allow any composition of namespaces using "." across multiple libraries.
+
+Using **uses** does NOT automatically import the remote library assets into the local file, but the local file can import those assets by referring to the assets from its contents. For example, a RAML type fragment file that uses a library of remote types can import one of those types by referring to it. The remote type is included as if it were defined locally within the RAML type fragment file.
+
+The following examples demonstrate the use of a library in a second library, a second library in a resource type fragment, and a second library in a RAML API definition.
+
+```yaml
+#%RAML 1.0 Library
+# This file is located at libraries/file-type.raml
+types:
+ File:
+ properties:
+ name:
+ length:
+ type: integer
+```
+
+```yaml
+#%RAML 1.0 Library
+# This file is located at libraries/files.raml
+usage: |
+ Use to define some basic file-related constructs.
+uses:
+ file-type: libraries/file-type.raml
+traits:
+ drm:
+ headers:
+ drm-key:
+resourceTypes:
+ file:
+ get:
+ is: [ drm ]
+ responses:
+ 201:
+ body:
+ application/json:
+ type: file-type.File
+ put:
+ is: [ drm ]
+
+```
+
+```yaml
+#%RAML 1.0 ResourceType
+# This file is located at files-resource.raml
+uses:
+ files: libraries/files.raml
+get:
+ is: [ files.drm ]
+```
+
+The following example is not valid because chaining namespaces is not allowed.
+
+```yaml
+#%RAML 1.0 ResourceType
+# Invalid RAML Fragment
+uses:
+ files: libraries/files.raml
+get:
+ is: [ files.drm ]
+ responses:
+ 200:
+ body:
+ application/json:
+ type: files.file-type.File # invalid - no chaining allowed
+```
+
+### Overlays and Extensions
+
+API definitions might need to be extended in a variety of ways for different needs. Annotations extend an API by adding metadata beyond that which is standardized in this RAML specification. Overlays of standard or non-standard metadata on top of an existing API definition can specify implementation details, or provide a translation of human-oriented documentation into different languages, without changing API behavior. Extending an API definition by adding to its behavior, or overriding certain aspects, is another way to satisfy different needs. RAML provides two mechanisms for extending API definitions: overlays and extensions.
+
+Overlays and extensions are RAML documents that add or override nodes of a RAML API definition. The first line of an overlay or extension document MUST begin with the text _#%RAML 1.0 Overlay_ or _#%RAML 1.0 Extension_, respectively, followed by nothing but the end of the line. An overlay or extension document MUST contain a root-level `extends` node whose value MUST be the location of a valid RAML API definition or another overlay or extension; the location specification is an absolute or relative path, or a URL, equivalent to an [!include tag argument](#includes). The document specified in the `extends` node is called the master RAML document.
+
+The remainder of an overlay or extension document follows the same rules as a RAML API definition, but with certain [restrictions](#overlays) in case of an overlay.
+
+To apply an overlay or extension, RAML processors MUST apply the [merging algorithm](#merging-rules) to the master RAML document and the extension or overlay, thereby producing a modified API definition; in the case of applying an overlay, the modified API definition is then validated against the master RAML document to adhere to the restrictions on overlays.
+
+To apply any combination of overlays and/or extensions, all must share the same master RAML document. The application process is:
+
+1. Apply the first overlay or extension to the master RAML document, producing a modified API definition and validating the result in the case of an overlay.
+2. Apply the second overlay or extension to the modified API definition as if the latter were the master RAML document, and again validate the result in the case of an overlay.
+3. Repeat the previous step until the last overlay or extension is applied.
+4. Resolve all !include tags before any application of the merging algorithm, validate restrictions on overlays after each overlay is applied, and apply all inheritances of types, resource types, traits, and annotation types.
+
+#### Overlays
+
+An overlay adds or overrides nodes of a RAML API definition while preserving its behavioral, functional aspects. Certain nodes of a RAML API definition specify the behavior of an API: its resources, methods, parameters, bodies, responses, and so on. These nodes cannot be changed by applying an overlay. In contrast, other nodes, such as descriptions or annotations, address concerns beyond the functional interface, such as the human-oriented descriptive documentation in some language, or implementation or verification information for use in automated tools. These nodes can be changed by applying an overlay.
+
+Overlays are particularly important for separating interface from implementation. Overlays enable separate lifecycles for the behavioral aspects of the API that need to be controlled tightly, such as a contract between the API provider and its consumers, versus those needing little control, such as the human- or implementation-oriented aspects that can evolve at different paces. For example, adding hooks for testing and monitoring tools, appending metadata relevant to a registry of APIs, or providing updated or translated human documentation can be achieved without changing any aspects of the behavioral aspects of the API. These things can be controlled through a rigorous version and change management process.
+
+It is difficult to draw a definitive line between the behavioral and implementation-oriented aspects of the API because, for example, some semantics of the API are often captured only in human documentation. RAML does, however, define the specific behavior-invariance restrictions on overlay files that processors MUST follow. Processors can then choose to offer the master API definition as well as its modifications after applying one or more overlays, so the consumer can benefit from all the information available. For example, if overlay files are provided as a means of localizing textual descriptions of resources, methods, and data, the consumer of generated documentation can be offered a choice of which localized overlays to apply.
+
+The behavior-invariance restrictions of an overlay are defined as follows: after applying the [merging algorithm](#merging-rules) as well as application of resource types and traits, the tree of nodes in the merged document is compared with the tree of nodes in the master RAML document after resolving all !include tags. Any differences in the documents MUST be only in the nodes listed in the following table.
+
+|Name | Allowed differences |
+|:--------|:------------|
+| title
description
documentation
usage
example | The merged tree can include new nodes of this type or nodes with different values from those in the master tree.
+| types | In addition to allowed differences described elsewhere in this table, the merged tree can also include new data types.
+| annotationTypes | The merged tree can include new annotation types or new values for existing annotation types, as long as all annotations in the merged API definition validate against the annotation types in the merged tree.
+| any annotation node | The merged tree can include new annotations of annotation types declared in the merged tree, or annotations with different values from those in the master tree.
+| examples | The merged tree can contain new named examples, or named examples with different values from those in the master tree.
+| documentation | The merged tree can contain new items in the array that is the value of the documentation root-level node. To change existing items, the documentation node itself can be overridden in the overlay.
+
+The following example illustrates a very simple RAML definition of a library books API, along with overlay files that provide a Spanish translation and metadata for an API monitoring service.
+
+```yaml
+#%RAML 1.0
+# This file is located at librarybooks.raml
+title: Book Library API
+documentation:
+ - title: Introduction
+ content: Automated access to books
+ - title: Licensing
+ content: Please respect copyrights on our books.
+/books:
+ description: The collection of library books
+ get:
+```
+
+```yaml
+#%RAML 1.0 Overlay
+usage: Spanish localization
+extends: librarybooks.raml
+documentation:
+ - title: Introducción
+ content: El acceso automatizado a los libros
+ - title: Licencias
+ content: Por favor respeta los derechos de autor de los libros
+/books:
+ description: La colección de libros de la biblioteca
+```
+
+```yaml
+#%RAML 1.0 Overlay
+usage: Hints for monitoring the library books API
+extends: librarybooks.raml
+annotationTypes:
+ monitor:
+ properties:
+ frequency:
+ properties:
+ interval: integer
+ unitOfMeasure:
+ enum: [ seconds, minutes, hours ]
+ script:
+/books:
+ get:
+ (monitor):
+ frequency:
+ interval: 5
+ unitOfMeasure: minutes
+ script: randomBooksFetch
+```
+
+#### Extensions
+
+An extension broadens a RAML API definition by adding to, or modifying aspects of its behavior and other functionality. An extension can be useful in separating a core, broadly-available API from layers of functionality available to more restricted audiences, for creating variants of an API for somewhat different purposes, or for specifying instance-specific nodes of an API, such as its service endpoint (URL) without altering its pure interface definition document.
+
+The following examples build on examples in the Overlays section by adding an extension for admins to add book items to a collection, adding an overlay to provide a translation of the added functionality, and adding an extension that locates a particular service endpoint of the API.
+
+```yaml
+#%RAML 1.0 Extension
+usage: Add administrative functionality
+extends: librarybooks.raml
+/books:
+ post:
+ description: Add a new book to the collection
+```
+
+```yaml
+#%RAML 1.0 Overlay
+usage: Spanish localization for admin functionality
+extends: librarybooks.raml
+/books:
+ post:
+ description: A?adir un nuevo libro para la colecci?n
+```
+
+```yaml
+#%RAML 1.0 Extension
+usage: The location of the public instance of the Piedmont library API
+extends: librarybooks.raml
+baseUri: http://api.piedmont-library.com
+```
+
+#### Merging Rules
+
+This section describes how an overlay/extension structure is applied to the master.
+
+##### Terminology
+
+###### Object & Property
+
+_Object_ is a MAP or a SEQUENCE containing MAPPINGS in terms of YAML.
+
+_Property_ is a MAPPING in terms of YAML, a key and its value pair.
+
+In the following example, the yellow "properties" is a _Property_ key, and the corresponding green _Object_ is the value.
+
+
+properties:
+ statusCode: 200
+ responseParameters:
+ type: object
+ description: "some description"
+
+
+In the same example, there is also a green "responseParameters" _Property_ key and its _Object_ value:
+
+
+properties:
+ statusCode: 200
+ responseParameters:
+ type: object
+ description: "some description"
+
+
+And while the yellow "statusCode", "type" and "description" are also properties, their values are not _Objects_:
+
+
+properties:
+ statusCode: 200
+ responseParameters:
+ type: object
+ description: "some description"
+
+
+In the following sample, yellow "FilteredByPrice" and "Paged" are _Properties_ with green _Object_ values.
+
+
+traits:
+ - FilterableByPrice:
+ queryParameters:
+ priceLessThen?:
+ type: number
+ priceMoreThen?:
+ type: number
+ - Paged:
+ queryParameters:
+ offset: number
+ length: number
+
+
+###### Array
+
+_Array_ is a SEQUENCE containing SCALARs or SEQUENCE containing MAPs in terms of YAML.
+
+In the following example, the yellow "enum" _Property_ key has a blue _Array_ value.
+
+
+enum:
+ - White
+ - Black
+ - Colored
+
+
+In this example of an _Array_ definition, a "documentation" _Property_ key has an _Array_ value that contains two green _Objects_:
+
+
+documentation:
+- title: Introduction
+ content: Automated access to books
+
+- title: Licensing
+ content: Please respect copyrights on our books.
+
+
+###### Property Types
+
+In the merging algorithm, the _Property_ types are referred to as _Property Kind_, which can be one of the following properties highlighted in **bold**:
+
+**_Object Property_** - a _Property_ having _Object_ as a value.
+
+In the following example, "properties" _Property_ is an _Object Property_:
+
+
+properties:
+ statusCode: 200
+ responseParameters:
+
+
+**_Array Property_** - a _Property_ having _Array_ of _Objects_ as a value.
+
+In the following example, "documentation" _Property_ is an _Object Property_:
+
+
+documentation:
+- title: Introduction
+ content: Automated access to books
+
+- title: Licensing
+ content: Please respect copyrights on our books.
+
+
+**_Simple property_** - a _Property_ having YAML SCALAR or a SEQUENCE of YAML SCALARS as a value.
+
+In the following sample "statusCode" and "enum" are simple properties.
+
+
+statusCode: 200
+enum:
+ - White
+ - Black
+ - Colored
+
+
+**_Single-value Simple Property_** - a Simple property having YAML SCALAR value.
+
+
+statusCode: 200
+
+
+**_Multi-value Simple Property_** - a Simple property having a SEQUENCE of YAML SCALARS as value.
+
+
+enum:
+ - White
+ - Black
+ - Colored
+
+
+Exceptions:
+* Examples are always _Simple Properties_ despite the capability to have complex YAML samples as values.
+* Annotations are always _Simple Properties_ despite potentially having a complex node structure.
+* Resource type applications are always _Simple Properties_.
+* Trait applications are always _Simple Properties_.
+* _Security Schema_ applications are always Simple Properties.
+
+###### Conflicting Properties
+
+Conflicting properties are the properties that cannot coexist in the same Object.
+
+In the following example, both "type" and "properties" _Properties_ can coexist, but the "enum" _Property_ cannot coexist with both "type" and "properties".
+
+
+color:
+ type: object
+ properties:
+ name: string
+ enum:
+ - White
+ - Black
+ - Colored
+
+
+###### Ignored properties
+
+_Ignored Properties_ - the following properties are considered ignored:
+"uses" and "usage".
+
+###### The Trees
+
+_Master Tree_ - Master file document YAML parsing tree result.
+_Extension Tree_ - overlay or extension YAML parsing tree result.
+_Target Tree_ - the result tree.
+
+##### Merging Algorithm:
+
+Master document and Extension or Overlay are parsed by YAML parser to produce _Master Tree_ and _Extension Tree_.
+
+_Master Tree_ and _Extension Tree_ are validated, in case of an error the merge process is cancelled.
+
+All _includes_ are resolved and applied for both _Master Tree_ and _Extension Tree_.
+
+All _uses_ are resolved and applied for both _Master Tree_ and _Extension Tree_. The trees MUST NOT have _uses_ instructions with the same namespace referring to different files.
+
+All Trait and Resource Types applications are applied in the _Master Tree_
+
+Initially, _Target Tree_ is made equal to the _Master Tree_.
+
+**Current Extension Tree Object** is set to the _Extension Tree_ root (API).
+**Current Target Tree Object** is set to the _Target Tree_ root (API).
+
+For each **Current Extension Tree Object property** the following is done:
+
+* If the **property** is an _Ignored Property_, continue to process the next property.
+* If the **property** with the same name exists in **Current Target Tree Object**:
+ * If the **property** and the identically named property in **Current Target Tree Object** have different _Property Kind_:
+ * The **property** value in the identically named **Current Target Tree Object** property is replaced with its value from **Current Extension Tree Object** property.
+ * If the **property** is a _Simple Property_
+ * If the **property** is a _Single-value Simple Property_,
+ * The **property** value in the identically named **Current Target Tree Object** property is replaced with its value from **Current Extension Tree Object** property.
+ * If the **property** is a _Multi-value Simple Property_
+ * The **property** value from **Current Extension Tree Object** property is added to the identically named **Current Target Tree Object** property values if no such value already exists.
+ * If the **property** is an _Object Property_:
+ * The same _Merging Algorithm_ is recursively performed for **Current Extension Tree Object** being set to the **property** value, and **Current Target Tree Object** being set to the value of the identically named property in **Current Target Tree Object**.
+ * If the **property** is an _Array Property_:
+ * _Objects_ from the property value are added to the identically named **Current Target Tree Object** property value.
+* If the **property** with the same name does not exist in **Current Target Tree Object**:
+ * All _Conflicting Properties_ are removed from the **Current Target Tree Object**
+ * The **property** is added to the **Current Target Tree Object**.
+
+Traits and Resource Types applications are applied one more time to the _Target Tree_.
+
+_Target Tree_ is validated.
+
+If the _Extension Tree_ is an Overlay, _Target Tree_ is compared to the _Master Tree_. There MUST NOT be any differences, other than those listed in the "Allowed differences" table in the [Overlays](#overlays) section. Otherwise the process is cancelled.
+
+_Target Tree_ has its resource types and Traits applied.
+
+_Target Tree_ is being serialized to a document or returned as the algorithm output.
+
+## References
+
+### Normative References
+
+Berners-Lee, T., Masinter, L., and M. McCahill, "Uniform Resource Locators (URL)", RFC 1738, December 1994.
+
+Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifiers (URI): Generic Syntax", RFC 2396, August 1998.
+
+Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
+
+Crockford, D., "The application/json Media Type for JavaScript Object Notation (JSON)", RFC 4627, July 2006.
+
+Dusseault, L. and J. Snell, "PATCH Method for HTTP", RFC 5789, March 2010.
+
+Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., and D. Orchard, "URI Template", RFC 6570, March 2012.
+
+Ben Kiki, O., Evans, C., and I. Net, "YAML Aint Markup Language", 2009, .
+
+### Informative References
+
+Galiegue, F., Zyp, K., and G. Court, "JSON Schema: core definitions and terminology", 2013, .
+
+Gruber, J., "Markdown Syntax Documentation", 2004, .
+
+Fielding, R., "Representational State Transfer (REST)", 2000, .
+
+Rose, M., "Writing I-Ds and RFCs using XML", RFC 2629, June 1999.
+
+Rescorla, E. and B. Korver, "Guidelines for Writing RFC Text on Security Considerations", BCP 72, RFC 3552, July 2003.
+
+Gao, S., Sperberg-McQueen, C., and H. Thompson, "W3C XML Schema Definition Language (XSD) 1.1", 2012, .