From 47d9a6959291d7ec38068c5700eb44ae89b0d30f Mon Sep 17 00:00:00 2001 From: Jonathan Stoikovitch Date: Tue, 11 Jun 2019 21:07:35 -0700 Subject: [PATCH 01/49] clarify additionalProperties --- 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 db29ef45..0500d278 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -576,7 +576,7 @@ All types that have the built-in object base type in its inheritance tree can us | properties? | The [properties](#property-declarations) that instances of this type can or must have. | minProperties? | The minimum number of properties allowed for instances of this type. | maxProperties? | The maximum number of properties allowed for instances of this type. -| additionalProperties? | A Boolean that indicates if an object instance has [additional properties](#additional-properties).

**Default:** `true` +| additionalProperties? | A Boolean that indicates whether an object instance MAY contain [additional properties](#additional-properties).

**Default:** `true` | discriminator? | Determines the concrete type of an individual object at runtime when, for example, payloads contain ambiguous types due to unions or inheritance. The value must match the name of one of the declared `properties` of a type. Unsupported practices are inline type declarations and [using `discriminator`](#using-discriminator) with non-scalar properties. | discriminatorValue? | Identifies the declaring type. Requires including a `discriminator` facet in the type declaration. A valid value is an actual value that might identify the type of an individual object and is unique in the hierarchy of the type. Inline type declarations are not supported.

**Default:** The name of the type From d0357be87d8f757f72bdb1396854c7cbdee5446d Mon Sep 17 00:00:00 2001 From: Jonathan Stoikovitch Date: Tue, 11 Jun 2019 21:07:35 -0700 Subject: [PATCH 02/49] clarify the definition of the additionalProperties facet of object types --- 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 db29ef45..0500d278 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -576,7 +576,7 @@ All types that have the built-in object base type in its inheritance tree can us | properties? | The [properties](#property-declarations) that instances of this type can or must have. | minProperties? | The minimum number of properties allowed for instances of this type. | maxProperties? | The maximum number of properties allowed for instances of this type. -| additionalProperties? | A Boolean that indicates if an object instance has [additional properties](#additional-properties).

**Default:** `true` +| additionalProperties? | A Boolean that indicates whether an object instance MAY contain [additional properties](#additional-properties).

**Default:** `true` | discriminator? | Determines the concrete type of an individual object at runtime when, for example, payloads contain ambiguous types due to unions or inheritance. The value must match the name of one of the declared `properties` of a type. Unsupported practices are inline type declarations and [using `discriminator`](#using-discriminator) with non-scalar properties. | discriminatorValue? | Identifies the declaring type. Requires including a `discriminator` facet in the type declaration. A valid value is an actual value that might identify the type of an individual object and is unique in the hierarchy of the type. Inline type declarations are not supported.

**Default:** The name of the type From 8a8fc2e5c8e52694463952d344cf8d354dea3052 Mon Sep 17 00:00:00 2001 From: Jonathan Stoikovitch Date: Fri, 14 Jun 2019 14:28:11 -0700 Subject: [PATCH 03/49] clarifying description (and examples) of integer and number scalar types --- versions/raml-10/raml-10.md | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 0500d278..d9dc709b 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -931,13 +931,13 @@ types: ##### Number -Any JSON number including [integer](#integer) with the following additional facets: +Any JSON number with the following additional facets: | Facet | Description | |:--------|:------------| -|minimum? | The minimum value of the parameter. Applicable only to parameters of type number or integer. -|maximum? | The maximum value of the parameter. Applicable only to parameters of type number or integer. -|format? | The format of the value. The value MUST be one of the following: int32, int64, int, long, float, double, int16, int8 +|minimum? | The minimum value. +|maximum? | The maximum value. +|format? | The format of the value. The value MUST be one of the following: int, int8, int16, int32, int64, long, float, double. |multipleOf? | A numeric instance is valid against "multipleOf" if the result of dividing the instance by this keyword's value is an integer. Example: @@ -946,24 +946,23 @@ Example: types: Weight: type: number - minimum: 3 - maximum: 5 - format: int64 - multipleOf: 4 + minimum: -1.1 + maximum: 20.9 + format: float + multipleOf: 1.1 ``` ##### Integer -A subset of JSON numbers that are positive and negative multiples of 1. The integer type inherits its facets from the [number type](#number). +Any JSON number, positive or negative multiple of 1. The integer type inherits its facets from the [number type](#number). ```yaml types: Age: type: integer - minimum: 3 + minimum: -3 maximum: 5 format: int8 - multipleOf: 1 ``` ##### Boolean From 842331b6d5ce51a13f0ff6c38b9770f51deb3a84 Mon Sep 17 00:00:00 2001 From: Jonathan Stoikovitch Date: Fri, 14 Jun 2019 15:29:26 -0700 Subject: [PATCH 04/49] Clarifying that the Any type has no ADDITIONAL facets --- 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 d9dc709b..e9a51490 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -565,7 +565,7 @@ Every type, whether built-in or user-defined, has the `any` type at the root of The "base" type of any type is the type in its inheritance tree that directly extends the `any` type at the root; thus, for example, if a custom type `status` extends the built-in type `integer` which extends the built-in type `number` which extends the `any` type, then the base type of `status` is `number`. Note that a type may have more than one base type. -The `any` type has no facets. +The `any` type has no additional facets. #### Object Type From 1873df421cee6262af7f10157894218adc16d004 Mon Sep 17 00:00:00 2001 From: Jonathan Stoikovitch Date: Fri, 14 Jun 2019 15:48:24 -0700 Subject: [PATCH 05/49] Fixed misuse of 'XSD' (XML Schema language) in the context of 'XML Schema' --- 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 e9a51490..a1f3985d 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1240,7 +1240,7 @@ type: !include elements.xsd#Foo When referencing an inner element of a schema, a RAML processor MUST validate an instance against that particular element. The RAML specification supports referencing any inner elements in JSON schemas that are valid schemas, any globally defined elements, and complex types in XML schemas. There are only a few restrictions: * Validation of any XML or JSON instance against inner elements follows the same restrictions as the validation against a regular XML or JSON schema. -* Referencing complex types inside an XSD is valid to determine the structure of an XML instance, but since complex types do not define a name for the top-level XML element, these types cannot be used for serializing an XML instance. +* Referencing complex types inside an XML Schema is valid to determine the structure of an XML instance, but since complex types do not define a name for the top-level XML element, these types cannot be used for serializing an XML instance. ### User-defined Facets From f4529873ba3ada1782a72f8ed571184f174276a2 Mon Sep 17 00:00:00 2001 From: Jonathan Stoikovitch Date: Fri, 14 Jun 2019 15:49:31 -0700 Subject: [PATCH 06/49] Fixed misuse of 'JSON Schemas' (files) in the context of 'JSON Schema' (language) --- 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 a1f3985d..034965f6 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -476,7 +476,7 @@ types: This section is informative. -The RAML type system borrows from object oriented programming languages such as Java, as well as from XSD and JSON Schemas. +The RAML type system borrows from object oriented programming languages such as Java, as well as from XSD and JSON Schema. RAML Types in a nutshell: From c61848974c4d0f89341ec6f3f512a91970da16db Mon Sep 17 00:00:00 2001 From: Jonathan Stoikovitch Date: Mon, 19 Aug 2019 17:49:05 -0700 Subject: [PATCH 07/49] typos and minor syntactic corrections --- versions/raml-10/raml-10.md | 148 ++++++++++++++++++------------------ 1 file changed, 74 insertions(+), 74 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 034965f6..0c8a8efa 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -80,7 +80,7 @@ Throughout this specification, **Markdown** means [GitHub-Flavored Markdown](htt - [File](#file) - [Nil Type](#nil-type) - [Union Type](#union-type) - - [Using XML and JSON Schema](#using-xml-and-json-schema) + - [Using XML and JSON Schemas](#using-xml-and-json-schemas) - [User-defined Facets](#user-defined-facets) - [Determine Default Types](#determine-default-types) - [Type Expressions](#type-expressions) @@ -148,7 +148,7 @@ RAML introduces the innovative concept of resource types and traits for characte This document is organized as follows: * **Basic Information**. How to describe core aspects of the API, such as its name, title, location (or URI), and defaults and how to include supporting documentation for the API. -* **Data Types**. Modeling API data through a streamlined type system that encompasses JSON and XML Schema. +* **Data Types**. Modeling API data through a streamlined type system that encompasses JSON Schema and XML Schema (XSD). * **Resources**. How to specify API resources and nested resources, as well as URI parameters in any URI templates. * **Methods**. How to specify the methods on API resources and their request headers, query parameters, and request bodies. * **Responses**. The specification of API responses, including status codes, media types, response headers, and response bodies. @@ -161,8 +161,8 @@ This document is organized as follows: * **Data types**: a unified, streamlined, and powerful way to model data wherever it appears in an API. * Uniformly covers bodies, URI parameters, headers, and query parameters and eliminates the need for a separate formParameters construct - * Supports wrapping XML Schema and JSON Schema and even referring to sub-schemas, but in many cases just obviates the schemas - * Simplifies coding, compared to the JSON Schema or XML Schema, by virtue of being YAML-based + * Supports wrapping XML and JSON schemas and even referring to sub-schemas, but in many cases just obviates the schemas + * Simplifies coding, compared to JSON Schema or XML Schema (XSD), by virtue of being YAML-based * **Examples**: multiple examples, expressible in YAML, and annotatable, so semantics can be injected * **Annotations**: a tried-and-tested, strongly-typed mechanism for extensibility * **Libraries**: improved modularity for broad reuse of API artifacts @@ -189,8 +189,8 @@ The media type _application/raml+yaml_ and its associated file extension _.raml_ To facilitate the automated processing of RAML documents, RAML imposes the following restrictions and requirements in addition to the core YAML 1.2 specification: -* The first line of a RAML file consists of a YAML comment that specifies the RAML version. Therefore, RAML processors cannot completely ignore all YAML comments. -* The order of some properties at certain levels within a RAML document is significant. Therefore, processors are expected to preserve this ordering. +* The first line of a RAML file MUST consist of a YAML comment that specifies the RAML version. Therefore, RAML processors SHALL NOT completely ignore all YAML comments. +* The order of some properties at certain levels within a RAML document is significant. Therefore, processors SHALL preserve this ordering. ## The Root of the Document @@ -250,7 +250,7 @@ The "schemas" and "types" nodes are mutually exclusive and synonymous: processor The OPTIONAL **documentation** node includes a variety of documents that serve as user guides and reference documentation for the API. Such documents can clarify how the API works or provide technical and business context. -The value of the documentation node is a sequence of one or more documents. Each document is a map that MUST have exactly two key-value pairs described in following table: +The value of the documentation node MUST be a sequence of one or more documents. Each document is a map that MUST have exactly two key-value pairs described in the following table: | Name | Description | |:----------|:----------| @@ -286,7 +286,7 @@ If the baseUri value is a [Template URI](#template-uri), the following reserved |:----------|:----------| | version | The value of the root-level version node -Any other URI template variables appearing in the baseUri MAY be described explicitly within a **baseUriParameters** node at the root of the API definition. The baseUriParameters node has the same structure and semantics as the [uriParameters](#template-uris-and-uri-parameters) node on a resource node, except that it specifies parameters in the base URI rather than the relative URI of a resource. +Any other URI template variables appearing in the baseUri MAY be described explicitly within a **baseUriParameters** node at the root of the API definition. The baseUriParameters node has the same semantics and therefor MUST follow the same structure as the [uriParameters](#template-uris-and-uri-parameters) node on a resource node, except that it specifies parameters in the base URI rather than the relative URI of a resource. The following example RAML API definition uses a [Template URI](#template-uri) as the base URI. @@ -328,7 +328,7 @@ baseUri: //api.test.com//common// ### Protocols -The OPTIONAL **protocols** node specifies the protocols that an API supports. If the protocols node is not explicitly specified, one or more protocols included in the baseUri node is used; if the protocols node is explicitly specified, the node specification overrides any protocol included in the baseUri node. The protocols node MUST be a non-empty array of strings, of values HTTP and/or HTTPS, and is case-insensitive. +The OPTIONAL **protocols** node specifies the protocols that an API supports. If the protocols node is not explicitly specified, one or more protocols included in the baseUri node SHALL be used; if the protocols node is explicitly specified, such node specification SHALL override any protocol included in the baseUri node. The protocols node MUST be a non-empty array of strings, of values HTTP and/or HTTPS, and is case-insensitive. The following is an example of an API endpoint that accepts both HTTP and HTTPS requests. @@ -344,7 +344,7 @@ baseUri: https://na1.salesforce.com/services/data/{version}/chatter Specifying the OPTIONAL **mediaType** node sets the default media type for responses and requests that have a body. You do not need to specify the media type within every body definition. -The value of the mediaType node MUST be a sequence of media type strings or a single media type string. The media type applies to requests having a body, the expected responses, and examples using the same sequence of media type strings. Each value needs to conform to the media type specification in [RFC6838](https://tools.ietf.org/html/rfc6838). +The value of the mediaType node MUST be a sequence of media type strings or a single media type string. The media type applies to requests having a body, the expected responses, and examples using the same sequence of media type strings. Each value MUST conform to the media type specification in [RFC6838](https://tools.ietf.org/html/rfc6838). This example shows a RAML snippet for an API that accepts and returns a JSON-formatted body. If the remainder of this API specification does not explicitly specify another media type, this API accepts and returns only JSON-formatted bodies. @@ -385,7 +385,7 @@ types: ### Default Security -Specifying the OPTIONAL **securedBy** node sets the default security schemes for, and protects, every method of every resource in the API. The value of the node is an array of security scheme names. See section [Applying Security Schemes](#applying-security-schemes) for more information, including how to resolve the application of multiple security schemes through inheritance. +Specifying the OPTIONAL **securedBy** node sets the default security schemes for, and protects, every method of every resource in the API. The value of the node MUST be an array of security scheme names. See section [Applying Security Schemes](#applying-security-schemes) for more information, including how to resolve the application of multiple security schemes through inheritance. The following example shows an API allowing access through either an OAuth 2.0 security scheme or an OAuth 1.1 security scheme. @@ -427,7 +427,7 @@ types: type: User ``` -A RAML type declaration resembles a JSON schema definition. In fact, RAML types can be used instead of JSON and XML schemas, or coexist with them. The RAML type syntax, however, is designed to be considerably easier and more succinct than JSON and XML schemas while retaining their flexibility and expressiveness. The following snippet shows a number of examples of type declarations: +A RAML type declaration resembles a JSON Schema definition. In fact, RAML types can be used instead of JSON and XML schemas, or coexist with them. The RAML type syntax, however, is designed to be considerably easier and more succinct than JSON and XML schemas while retaining their flexibility and expressiveness. The following snippet shows a number of examples of type declarations: ```yaml #%RAML 1.0 @@ -476,7 +476,7 @@ types: This section is informative. -The RAML type system borrows from object oriented programming languages such as Java, as well as from XSD and JSON Schema. +The RAML type system borrows from object oriented programming languages such as Java, as well as from XML Schema (XSD) and JSON Schema. RAML Types in a nutshell: @@ -495,7 +495,7 @@ RAML Types in a nutshell: ### Defining Types -Types can be declared inline where the API expects data, in an OPTIONAL **types** node at the root of the API, or in an included library. To declare a type, you use a map where the key represents the name of the type and its value is a [type declaration](#type-declarations). +Types SHALL either be declared inline where the API expects data, in an OPTIONAL **types** node at the root of the API, or in an included library. To declare a type, you MUST use a map where the key represents the name of the type and its value is a [type declaration](#type-declarations). ```yaml types: @@ -553,7 +553,7 @@ The RAML type system defines the following built-in types: * [union](#union-type) via type expression * one of the following [scalar types](#scalar-types): number, boolean, string, date-only, time-only, datetime-only, datetime, file, integer, or nil -Additional to the built-in types, the RAML type system also allows to define [JSON or XML schema](#using-xml-and-json-schema). +Additional to the built-in types, the RAML type system also allows to define [JSON or XML schemas](#using-xml-and-json-schemas). The following diagram shows the inheritance tree, starting at the root-level with `any`. @@ -569,7 +569,7 @@ The `any` type has no additional facets. #### Object Type -All types that have the built-in object base type in its inheritance tree can use the following facets in their type declarations: +All types that have the built-in object base type in its inheritance tree MAY use the following facets in their type declarations: | Facet | Description | |:----------|:----------| @@ -596,9 +596,9 @@ types: ##### Property Declarations -Properties of object types are defined using the OPTIONAL **properties** facet. The RAML Specification calls the value of the "properties" facet a "properties declaration". The properties declaration is a map of keys and values. The keys are valid property names for declaring a type instance. The values are either a name of a type or an inline type declaration. +Properties of object types are defined using the OPTIONAL **properties** facet. The RAML Specification calls the value of the "properties" facet a "properties declaration". The properties declaration MUST be a map of keys and values. The keys are valid property names for declaring a type instance. The values MUST be either a name of a type or an inline type declaration. -The properties declaration can specify whether a property is required or optional. +The properties declaration MAY specify whether a property is required or optional. | Facet | Description | |:----------|:----------| @@ -670,7 +670,7 @@ When an object type does not contain the "properties" facet, the object is assum ##### Additional Properties -By default, any instance of an object can have additional properties beyond those specified in its data type `properties` facet. Assume the following code is an instance of the data type `Person` that is described in the previous section. +By default, any instance of an object MAY have additional properties beyond those specified in its data type `properties` facet. Assume the following code is an instance of the data type `Person` that is described in the previous section. ```yaml Person: @@ -681,7 +681,7 @@ Person: The property `note` is not explicitly declared in the `Person` data type, but is valid because all additional properties are valid by default. -To restrict the addition of properties, you can set the value of the `additionalProperties` facet to `false`, or you can specify regular expression patterns that match sets of keys and restrict their values. The latter are called "pattern properties". The patterns are delineated by pairs of opening and closing `/` characters, as follows: +To restrict the addition of properties, you MAY set the value of the `additionalProperties` facet to `false`, or you MAY specify regular expression patterns that match sets of keys and restrict their values. The latter are called "pattern properties". The patterns are delineated by pairs of opening and closing `/` characters, as follows: ```yaml #%RAML 1.0 @@ -735,7 +735,7 @@ Moreover, if `additionalProperties` is `false` (explicitly or by inheritance) in ##### Object Type Specialization -You can declare object types that inherit from other object types. A sub-type inherits all the properties of its parent type. In the following example, the type `Employee` inherits all properties of its parent type `Person`. +You MAY declare object types that inherit from other object types. A sub-type inherits all the properties of its parent type. In the following example, the type `Employee` inherits all properties of its parent type `Person`. ```yaml #%RAML 1.0 @@ -753,15 +753,15 @@ types: type: string ``` -A sub-type can override properties of its parent type with the following restrictions: 1) a required property in the parent type cannot be changed to optional in the sub-type, and 2) the type declaration of a defined property in the parent type can only be changed to a narrower type (a specialization of the parent type) in the sub-type. +A sub-type MAY override properties of its parent type with the following restrictions: 1) a required property in the parent type cannot be changed to optional in the sub-type, and 2) the type declaration of a defined property in the parent type can only be changed to a narrower type (a specialization of the parent type) in the sub-type. ##### Using Discriminator When payloads contain ambiguous types due to unions or inheritance, it is often impossible to discriminate the concrete type of an individual object at runtime. For example, when deserializing the payload into a statically typed language, this problem can occur. -A RAML processor might provide an implementation that automatically selects a concrete type from a set of possible types, but a simpler alternative is to store some unique value associated with the type inside the object. +A RAML processor MAY provide an implementation that automatically selects a concrete type from a set of possible types, but a simpler alternative is to store some unique value associated with the type inside the object. -You set the name of an object property using the `discriminator` facet. The name of the object property is used to discriminate the concrete type. The `discriminatorValue` stores the actual value that might identify the type of an individual object. By default, the value of `discriminatorValue` is the name of the type. +You MAY set the name of an object property using the `discriminator` facet. The name of the object property MAY be used to discriminate the concrete type. The `discriminatorValue` stores the actual value that MAY identify the type of an individual object. By default, the value of `discriminatorValue` is the name of the type. Here's an example that illustrates how to use `discriminator`: @@ -795,7 +795,7 @@ data: kind: Employee ``` -You can also override the default for `discriminatorValue` for each individual concrete class. The following example replaces the default value of `discriminatorValue` in initial caps with lowercase: +You MAY also override the default for `discriminatorValue` for each individual concrete class. The following example replaces the default value of `discriminatorValue` in initial caps with lowercase: ```yaml #%RAML 1.0 @@ -829,7 +829,7 @@ data: kind: employee ``` -Neither `discriminator` nor `discriminatorValue` can be defined for any inline type declarations or union types. +`discriminator` and `discriminatorValue` MUST NOT be defined in any inline type declarations or union types. ```yaml # valid whenever there is a key name that can identify a type @@ -857,7 +857,7 @@ PersonOrDog: #### Array Type -Array types are declared by using either the array qualifier `[]` at the end of a [type expression](#type-expressions) or `array` as the value of a `type` facet. If you are defining a top-level array type, such as the `Emails` in the examples below, you can declare the following facets in addition to those previously described to further restrict the behavior of the array type. +Array types MUST be declared by using either the array qualifier `[]` at the end of a [type expression](#type-expressions) or `array` as the value of a `type` facet. If you are defining a top-level array type, such as the `Emails` in the examples below, you MAY declare the following facets in addition to those previously described to further restrict the behavior of the array type. | Facet | Description | |:----------|:----------| @@ -1033,7 +1033,7 @@ types: ##### Nil Type -In RAML, the type `nil` is a scalar type that allows only nil data values. Specifically, in YAML it allows only YAML's `null` (or its equivalent representations, such as `~`), in JSON it allows only JSON's `null`, and in XML it allows only XML's `xsi:nil`. In headers, URI parameters, and query parameters, the `nil` type only allows the string value "nil" (case-sensitive); and in turn an instance having the string value "nil" (case-sensitive), when described with the `nil` type, deserializes to a nil value. +In RAML, the type `nil` is a scalar type that SHALL allow only nil data values. Specifically, in YAML it allows only YAML's `null` (or its equivalent representations, such as `~`), in JSON it allows only JSON's `null`, and in XML it allows only XML's `xsi:nil`. In headers, URI parameters, and query parameters, the `nil` type SHALL only allow the string value "nil" (case-sensitive); and in turn an instance having the string value "nil" (case-sensitive), when described with the `nil` type, SHALL deserialize to a nil value. In the following example, the type is an object and has two required properties, `name` and `comment`, both defaulting to type `string`. In `example`, `name` is assigned a string value, but comment is nil and this is _not_ allowed because RAML expects a string. @@ -1082,7 +1082,7 @@ Declaring the type of a property to be `nil` represents the lack of a value in a #### Union Type -A union type is used to allow instances of data to be described by any of several types. A union type is declared via a type expression that combines 2 or more types delimited by pipe (`|`) symbols; these combined types are referred to as the union type's super types. In the following example, instances of the `Device` type may be described by either the `Phone` type or the `Notebook` type: +A union type MAY be used to allow instances of data to be described by any of several types. A union type MUST be declared via a type expression that combines 2 or more types delimited by pipe (`|`) symbols; these combined types are referred to as the union type's super types. In the following example, instances of the `Device` type MAY be described by either the `Phone` type or the `Notebook` type: ```yaml #%RAML 1.0 @@ -1108,7 +1108,7 @@ types: type: Phone | Notebook ``` -An instance of a union type is valid if and only if it meets all restrictions associated with at least one of the super types. More generally, an instance of a type that has a union type in its type hierarchy is valid if and only if it is a valid instance of at least one of the super types obtained by expanding all unions in that type hierarchy. Such an instance is deserialized by performing this expansion and then matching the instance against all the super types, starting from the left-most and proceeding to the right; the first successfully-matching base type is used to deserialize the instance. +An instance of a union type SHALL be considered valid if and only if it meets all restrictions associated with at least one of the super types. More generally, an instance of a type that has a union type in its type hierarchy SHALL be considered valid if and only if it is a valid instance of at least one of the super types obtained by expanding all unions in that type hierarchy. Such an instance is deserialized by performing this expansion and then matching the instance against all the super types, starting from the left-most and proceeding to the right; the first successfully-matching base type is used to deserialize the instance. The following example defines two types and a third type which is a union of those two types. @@ -1169,7 +1169,7 @@ types: HomeAnimal: [ HasHome | IsOnFarm , Dog | Cat | Parrot ] ``` -#### Using XML and JSON Schema +#### Using XML and JSON Schemas RAML allows the use of XML and JSON schemas to describe the body of an API request or response by integrating the schemas into its data type system. @@ -1190,7 +1190,7 @@ types: type: !include person.json ``` -A RAML processor MUST NOT allow types that define an XML or JSON schema to participate in type inheritance or specialization, or effectively in any [type expression](#type-expressions). Therefore, you cannot define sub-types of these types to declare new properties, add restrictions, set facets, or declare facets. You can, however, create simple type wrappers that add annotations, examples, display name, or a description. +A RAML processor MUST NOT allow types that define an XML or JSON schema to participate in type inheritance or specialization, or effectively in any [type expression](#type-expressions). Therefore, you SHALL NOT define sub-types of these types to declare new properties, add restrictions, set facets, or declare facets. You MAY, however, create simple type wrappers that add annotations, examples, display name, or a description. The following example shows a valid declaration. @@ -1223,15 +1223,15 @@ types: members: Person[] # invalid use of type expression '[]' and as a property type ``` -A RAML processor MUST be able to interpret and apply JSON Schema and XML Schema. +A RAML processor MUST be able to interpret and apply JSON and XML schemas. -An XML schema, or JSON schema, MUST NOT be used where the media type does not allow XML-formatted data, or JSON-formatted data, respectively. XML and JSON schemas are also forbidden in any declaration of query parameters, query string, URI parameters, and headers. +A XML schema, or JSON schema, MUST NOT be used where the media type does not allow XML-formatted data, or JSON-formatted data, respectively. XML and JSON schemas are also forbidden in any declaration of query parameters, query string, URI parameters, and headers. The nodes "schemas" and "types", as well as "schema" and "type", are mutually exclusive and synonymous for compatibility with RAML 0.8. API definitions SHOULD use "types" and "type", as "schemas" and "schema" are deprecated and might be removed in a future RAML version. ##### References to Inner Elements -Sometimes it is necessary to refer to an element defined in a schema. RAML supports that by using URL fragments as shown in the example below. +Sometimes it MAY be necessary to refer to an element defined in a schema. RAML supports that by using URL fragments as shown in the example below. ```yaml type: !include elements.xsd#Foo @@ -1239,14 +1239,14 @@ type: !include elements.xsd#Foo When referencing an inner element of a schema, a RAML processor MUST validate an instance against that particular element. The RAML specification supports referencing any inner elements in JSON schemas that are valid schemas, any globally defined elements, and complex types in XML schemas. There are only a few restrictions: -* Validation of any XML or JSON instance against inner elements follows the same restrictions as the validation against a regular XML or JSON schema. -* Referencing complex types inside an XML Schema is valid to determine the structure of an XML instance, but since complex types do not define a name for the top-level XML element, these types cannot be used for serializing an XML instance. +* Validation of any XML or JSON instance against inner elements MUST follow the same restrictions as the validation against a regular XML or JSON schema. +* Referencing complex types inside an XML schema is valid to determine the structure of an XML instance, but since complex types do not define a name for the top-level XML element, these types SHALL NOT be used for serializing an XML instance. ### User-defined Facets Facets express various additional restrictions beyond those which types impose on their instances, such as the optional `minimum` and `maximum` facets for numbers, or the `enum` facet for scalars. In addition to the built-in facets, RAML provides a way to declare user-defined facets for any data type. -The user-defined facet is declared using the OPTIONAL `facets` facet in a type declaration. The value of the `facets` facet is a map. The key names the user-defined facet. The corresponding value defines the concrete value that the respective facet can take. The syntax of a [property declaration](#property-declarations) and user-defined facet declaration are the same. A facet restricts instances of a subtype, not its type, based on the concrete value defined in the facet declaration. +The user-defined facet is declared using the OPTIONAL `facets` facet in a type declaration. The value of the `facets` facet MUST be a map. The key names the user-defined facet. The corresponding value defines the concrete value that the respective facet can take. The syntax of a [property declaration](#property-declarations) and user-defined facet declaration are the same. A facet restricts instances of a subtype, not its type, based on the concrete value defined in the facet declaration. Facet names MUST NOT begin with open parenthesis, to disambiguate the names from annotations. User-defined facet names on a type MUST NOT match built-in facets on that type, nor facet names of any ancestor type in the inheritance chain of the type. @@ -1270,11 +1270,11 @@ types: In this example, declaring the `noHolidays` facet and defining its values to be boolean makes it possible to restrict date instances that fall on holidays. Instances of any inheriting type, such as the `PossibleMeetingDate` type, must have values that do not fall on holidays. -User-defined facets by definition are not built into this RAML specification, and hence their semantic might not be understood by all RAML processors. Consequently, a RAML processor may or may not choose to use user-defined facets on a type in validating instances of that type. In the example above, a RAML processor may or may not assign a meaning to `noHolidays`, and therefore, may choose to ignore the `noHolidays: true` value in validating instances of `PossibleMeetingDate`. +User-defined facets by definition are not built into this RAML specification, and hence their semantic MAY not be understood by all RAML processors. Consequently, a RAML processor may or may not choose to use user-defined facets on a type in validating instances of that type. In the example above, a RAML processor may or may not assign a meaning to `noHolidays`, and therefore, may choose to ignore the `noHolidays: true` value in validating instances of `PossibleMeetingDate`. ### Determine Default Types -A RAML processor must be able to determine the default type of a type declaration by using the following rules: +A RAML processor MUST be able to determine the default type of a type declaration by using the following rules: * If, and only if, a type declaration contains a `properties` facet, then the default type is `object`. The following snippet exemplifies this rule: @@ -1330,7 +1330,7 @@ types: ### Type Expressions -Type expressions provide a powerful way of referring to, and even defining, types. Type expressions can be used wherever a type is expected. The simplest type expression is just the name of a type. Using type expressions, you can devise type unions, arrays, maps, and other things. +Type expressions provide a powerful way of referring to, and even defining, types. Type expressions MAY be used wherever a type is expected. The simplest type expression is just the name of a type. Using type expressions, you MAY devise type unions, arrays, maps, and other things. |Expression | Description | |:--------|:------------| @@ -1426,7 +1426,7 @@ types: In the example above, the type `Teacher` inherits all restrictions from `Person` and `Employee`. -Multiple inheritance is allowed only if the sub-type is still a valid type declaration after inheriting all restrictions from its parent types. Also, it is not allowed to inherit from different kind of primitive types, for example `[ number, string ]`. +Multiple inheritance SHALL be allowed only if the sub-type is still a valid type declaration after inheriting all restrictions from its parent types. Also, it SHALL not be allowed to inherit from different kind of primitive types, for example `[ number, string ]`. In the following example, the sub-type `Number3` is fully valid: @@ -1456,11 +1456,11 @@ types: Section [union types](#union-multiple-inheritance) illustrates another example of how to validate types that use multiple inheritance and union types. -If a sub-type inherits properties having the same name from at least two of its parent types, the sub-type keeps all restrictions applied to those properties with two exceptions: 1) a "pattern" facet when a parent type already declares a "pattern" facet 2) a user-defined facet when another user-defined facet has the same value. In these cases, an invalid type declaration occurs. +If a sub-type inherits properties having the same name from at least two of its parent types, the sub-type SHALL keep all restrictions applied to those properties with two exceptions: 1) a "pattern" facet when a parent type already declares a "pattern" facet 2) a user-defined facet when another user-defined facet has the same value. In these cases, an invalid type declaration occurs. ### Inline Type Declarations -You can declare inline/anonymous types everywhere a type can be referenced except in a Type Expression. +You MAY declare inline/anonymous types everywhere a type can be referenced except in a Type Expression. ```yaml #%RAML 1.0 @@ -1487,7 +1487,7 @@ It is highly RECOMMENDED that API documentation include a rich selection of exam #### Multiple Examples -The OPTIONAL **examples** facet can be used to attach multiple examples to a type declaration. Its value is a map of key-value pairs, where each key represents a unique identifier for an example and the value is a [single example](#single-example). +The OPTIONAL **examples** facet MAY be used to attach multiple examples to a type declaration. Its value MUST be a map of key-value pairs, where each key represents a unique identifier for an example and the value is a [single example](#single-example). The following example shows the value of an **examples** facet: @@ -1504,7 +1504,7 @@ record: # {key} - unique id #### Single Example -The OPTIONAL **example** facet can be used to attach an example of a type instance to the type declaration. There are two ways to represent the example facet value: as an explicit description of a specific type instance and as a map that contains additional facets. +The OPTIONAL **example** facet MAY be used to attach an example of a type instance to the type declaration. There are two ways to represent the example facet value: as an explicit description of a specific type instance and as a map that contains additional facets. ##### As an explicit description of a specific type instance @@ -1517,15 +1517,15 @@ body: You have been added to group 274 ##### As a map that contains additional facets -The map can contain the following additional facets: +The map MAY contain the following additional facets: | Facet | Description | |:--------|:------------| | displayName? | An alternate, human-friendly name for the example. If the example is part of an examples node, the default value is the unique identifier that is defined for this example. -| description? | A substantial, human-friendly description for an example. Its value is a string and 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. +| description? | A substantial, human-friendly description for an example. Its value MUST be a string and MAY be formatted using [markdown](#markdown). +| (<annotationName>)? | [Annotations](#annotations) to be applied to this API. An annotation MUST be 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. | value | The actual example of a type instance. -| strict? | Validates the example against any type declaration (the default), or not. Set this to false avoid validation. +| strict? | Validates the example against any type declaration (the default), or not. Set this to false to avoid validation. For example: @@ -1593,7 +1593,7 @@ types: ### XML Serialization of Type Instances -To facilitate the potentially complex process of serialization to XML, RAML introduces an additional `xml` node for [type declarations](#type-declarations). This node is used to configure how type instances SHOULD be serialized to XML. The value of the `xml` node is a map that contains the following nodes: +To facilitate the potentially complex process of serialization to XML, RAML introduces an additional `xml` node for [type declarations](#type-declarations). This node MAY be used to configure how type instances SHOULD be serialized to XML. The value of the `xml` node MUST be a map that contains the following nodes: | Name | Type | Description | |:---------|:------:|:-----------------| @@ -1637,7 +1637,7 @@ The example above can be serialized into the following XML: ### Using Types in RAML -Types can be used in several positions: +Types MAY be used in several positions: * Body ( JSON ) * Body ( XML ) * Body ( Web Form ) @@ -1741,23 +1741,23 @@ The URIs in the following example would ALWAYS be ALLOWED. ### Resource Property -The value of a resource node is a map whose key-value pairs are described in the following table. +The value of a resource node MUST be a map whose key-value pairs are described in the following table. | Name | Description | |:--------|:------------| | displayName? | An alternate, human-friendly name for the resource. If the displayName node is not defined for a resource, documentation tools SHOULD refer to the resource by its key, which acts as the resource name. For example, tools SHOULD refer to the relative URI `/jobs`. -| description? | A substantial, human-friendly description of a resource. Its value is a string and 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. +| description? | A substantial, human-friendly description of a resource. Its value MUST be a string and MAY be formatted using [markdown](#markdown). +| (<annotationName>)? | [Annotations](#annotations) to be applied to this API. An annotation MUST be 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. | get?
patch?
put?
post?
delete?
options?
head? | The object describing the [method](#methods). | is? | A list of [traits to apply](#applying-resource-types-and-traits) to all methods declared (implicitly or explicitly) for this resource. Individual methods can override this declaration. | type? | The [resource type](#applying-resource-types-and-traits) that this resource inherits. | securedBy? | The [security schemes](#applying-security-schemes) that apply to all methods declared (implicitly or explicitly) for this resource. | uriParameters? | Detailed information about any URI parameters of this resource. -| /<relativeUri>? | A nested resource, which is identified as any node whose name begins with a slash (`/`), and is therefore treated as a relative URI. +| /<relativeUri>? | A nested resource, which is identified as any node whose name begins with a slash (`/`), and SHALL therefore be treated as a relative URI. ### Template URIs and URI Parameters -[Template URIs](#template-uri) containing URI parameters can be used to define a relative URI of a resource that contains variable elements. The following example shows a top-level resource with a key `/jobs` and a nested resource with a key `/{jobId}`, a template URI. +[Template URIs](#template-uri) containing URI parameters MAY be used to define a relative URI of a resource that contains variable elements. The following example shows a top-level resource with a key `/jobs` and a nested resource with a key `/{jobId}`, a template URI. ```yaml #%RAML 1.0 @@ -1833,9 +1833,9 @@ version: v1 description: An item in the collection of all files ``` -Although a URI parameter can be explicitly specified as optional, it SHOULD be required when surrounded directly by slashes (`/`). In this case, the URI parameter constitutes a complete URI path fragment, for example `.../{objectId}/...`. It usually makes no sense to allow a URI to contain adjacent slashes, enclosing no characters, for example `...//...`. Hence, a URI parameter SHOULD be specified as optional only when it appears adjacent to other text. For example, `/people/~{fieldSelectors}` indicates that URI parameter `{fieldSelectors}` can be blank, and therefore optional, implying that `/people/~` is a valid relative URI. +Although a URI parameter MAY be explicitly specified as optional, it SHOULD be required when surrounded directly by slashes (`/`). In this case, the URI parameter constitutes a complete URI path fragment, for example `.../{objectId}/...`. It usually makes no sense to allow a URI to contain adjacent slashes, enclosing no characters, for example `...//...`. Hence, a URI parameter SHOULD be specified as optional only when it appears adjacent to other text. For example, `/people/~{fieldSelectors}` indicates that URI parameter `{fieldSelectors}` can be blank, and therefore optional, implying that `/people/~` is a valid relative URI. -A special URI reserved parameter, **ext**, might or might not be specified explicitly in a uriParameters node. Its meaning is reserved for use by a client to specify that the body of the request or response be of the associated media type. +A special URI reserved parameter, **ext**, MAY be specified explicitly in a uriParameters node. Its meaning is reserved for use by a client to specify that the body of the request or response be of the associated media type. |URI Parameter | Value | |:--------|:------------| @@ -1856,7 +1856,7 @@ version: v1 ## Methods -RESTful API methods are operations that are performed on a resource. The OPTIONAL properties **get**, **patch**, **put**, **post**, **delete**, **head**, and **options** of a resource define its methods; these correspond to the HTTP methods defined in the HTTP version 1.1 specification [RFC2616](https://www.ietf.org/rfc/rfc2616.txt) and its extension, [RFC5789](https://tools.ietf.org/html/rfc5789). The value of these method properties is a map that has the following key-value pairs: +RESTful API methods are operations that are performed on a resource. The OPTIONAL properties **get**, **patch**, **put**, **post**, **delete**, **head**, and **options** of a resource define its methods; these correspond to the HTTP methods defined in the HTTP version 1.1 specification [RFC2616](https://www.ietf.org/rfc/rfc2616.txt) and its extension, [RFC5789](https://tools.ietf.org/html/rfc5789). The value of these method properties MUST be a map with the following key-value pairs: | Name | Description | |:--------|:------------| @@ -1874,7 +1874,7 @@ RESTful API methods are operations that are performed on a resource. The OPTIONA ### Headers -An API's methods can support or require various HTTP headers. The OPTIONAL **headers** node is used to explicitly specify those headers. The value of the headers node is a map, specifically a [properties declaration](#property-declarations), as is the value of the properties object of a type declaration. Each property in this declaration object is a header **declaration**. Each property name specifies an allowed header name. Each property value specifies the header value type as a type name or an inline type declaration. +An API's methods MAY support or require various HTTP headers. The OPTIONAL **headers** node MAY be used to explicitly specify those headers. The value of the headers node MUST be a map, specifically a [properties declaration](#property-declarations), as is the value of the properties object of a type declaration. Each property in this declaration object is a header **declaration**. Each property name specifies an allowed header name. Each property value specifies the header value type as a type name or an inline type declaration. The following simple example shows a post method with a single HTTP header named Zencoder-Api-Key of (implied) string type. @@ -1940,11 +1940,11 @@ traits: ### Query Strings and Query Parameters -An API method can support or require a query string in the URL on which the method is invoked. The query string in a URL is defined in [RFC3986](https://www.ietf.org/rfc/rfc3986.txt) as the part of the URL following the question mark separator (`?`) and preceding any fragment (`#`) separator. The query string can be specified either by the OPTIONAL **queryString** node or by the OPTIONAL **queryParameters** node. The queryString and queryParameters nodes are mutually exclusive: processors MUST NOT allow both to be specified, explicitly or implicitly, on the same method of the same resource. +An API method MAY support or require a query string in the URL on which the method is invoked. The query string in a URL MUST follow [RFC3986](https://www.ietf.org/rfc/rfc3986.txt) as the part of the URL following the question mark separator (`?`) and preceding any fragment (`#`) separator. The query string MAY be specified either by the OPTIONAL **queryString** node or by the OPTIONAL **queryParameters** node. The queryString and queryParameters nodes SHALL BE mutually exclusive: processors MUST NOT allow both to be specified, explicitly or implicitly, on the same method of the same resource. #### The Query String as a Whole -The **queryString** node is used to specify the query string as a whole, rather than as name-value pairs. The queryString value is either the name of a data type or an inline data type declaration, including a data type expression. In either case, all base types in type hierarchy of the data type MUST be either a scalar type or the object type, after fully expanding any union type expressions at every level of the type hierarchy. +The **queryString** node MAY be used to specify the query string as a whole, rather than as name-value pairs. The queryString value MUST either be the name of a data type or an inline data type declaration, including a data type expression. In either case, all base types in type hierarchy of the data type MUST be either a scalar type or the object type, after fully expanding any union type expressions at every level of the type hierarchy. If the type is derived from a scalar type, the query string as a whole MUST be described by the type. @@ -2029,9 +2029,9 @@ baseUri: https://api.github.com/{version} ### Bodies -The HTTP request **body** for a method is specified using the OPTIONAL body node. For example, to create a resource using a POST or PUT, the body of the request would usually include the details of the resource to be created. +The HTTP request **body** for a method MAY be specified using the OPTIONAL body node. For example, to create a resource using a POST or PUT, the body of the request would usually include the details of the resource to be created. -The value of the body node is a "body declaration". Generally, the body declaration is a map whose key names are the valid media types of the request body. Each key name MUST be a media type string conforming to the media type specification in [RFC6838](https://tools.ietf.org/html/rfc6838). The values are the corresponding data type declaration or data type name describing the request body. Alternatively, if [default media types](#default-media-types) have been declared at the root of the API, then the body declaration can consist of just the data type declaration or data type name describing the request body for that media type. +The value of the body node is a "body declaration". Generally, the body declaration SHOULD be a map whose key names are the valid media types of the request body. Each key name MUST be a media type string conforming to the media type specification in [RFC6838](https://tools.ietf.org/html/rfc6838). The values are the corresponding data type declaration or data type name describing the request body. Alternatively, if [default media types](#default-media-types) have been declared at the root of the API, then the body declaration MAY consist of just the data type declaration or data type name describing the request body for that media type. The following example illustrates various combinations of both default and non-default media types, and both data type declarations and references. @@ -2064,18 +2064,18 @@ types: The resources and methods sections of this document describe HTTP requests. This section describes the HTTP responses to method invocations on resources. -The OPTIONAL **responses** node of a method on a resource describes the possible responses to invoking that method on that resource. The value of **responses** is a map where each key name represents that a possible HTTP status codes for that method on that resource. The values describe the corresponding responses. Each value is a [response declaration](#response-declaration). +The OPTIONAL **responses** node of a method on a resource describes the possible responses to invoking that method on that resource. The value of **responses** MUST be a map where each key name represents that a possible HTTP status codes for that method on that resource. The values describe the corresponding responses. Each value MUST be a [response declaration](#response-declaration). -Keys are often numeric, for example 200 or 204. Processors MUST treat these numeric keys as string keys in all situations. For example, '200' and 200 MUST be treated as duplicate keys, and therefore, are not allowed simultaneously. +Keys SHOULD BE numeric, for example 200 or 204. Processors MUST treat these numeric keys as string keys in all situations. For example, '200' and 200 MUST be treated as duplicate keys, and therefore, are not allowed simultaneously. ### Response Declaration -The value of a response declaration is a map that can contain any of the following key-value pairs: +The value of a response declaration MUST be a map with the following key-value pairs | Name | Description | |:--------|:------------| -| description? | A substantial, human-friendly description of a response. Its value is a string and 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. +| description? | A substantial, human-friendly description of a response. Its value MUST ve a string and MAY be formatted using [markdown](#markdown). +| (<annotationName>) | [Annotations](#annotations) to be applied to this API. An annotation MUST be 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. | headers? | Detailed information about any response headers returned by this method | body? | The body of the response @@ -2135,11 +2135,11 @@ A trait, like a method, can provide method-level nodes such as description, head ### Declaring Resource Types and Traits -Resource types can be declared using the OPTIONAL **resourceTypes** node at the root of the API definition. The value of this node is a map where keys names become names of resource types that can be referenced throughout the API, and values are resource type declarations. +Resource types MAY be declared using the OPTIONAL **resourceTypes** node at the root of the API definition. The value of this node MUST be a map where keys names become names of resource types that MAY be referenced throughout the API, and values are resource type declarations. -Similarly, traits can be declared using the OPTIONAL **traits** node at the root of the API definition. The value of this node is a map where key names become names of traits that can be referenced throughout the API, and values are trait declarations. +Similarly, traits MAY be declared using the OPTIONAL **traits** node at the root of the API definition. The value of this node MUST be a map where key names become names of traits that MAY be referenced throughout the API, and values are trait declarations. -Resource type and trait declarations can have the following nodes, in addition to all the nodes that resources and methods can have, respectively (except that resource type declarations MUST NOT have nested resource nodes). +Resource type and trait declarations MAY have the following nodes, in addition to all the nodes that resources and methods can have, respectively (except that resource type declarations MUST NOT have nested resource nodes). | Name | Definition | |:---------|:-----------| @@ -2197,7 +2197,7 @@ resourceTypes: ### Applying Resource Types and Traits -A resource can specify the resource type from which it is derived using the OPTIONAL **type** node. The value MUST be the name of a resource type defined within the root-level resourceTypes node or in a library. Resource type definitions do not apply to existing nested resources. +A resource MAY specify the resource type from which it is derived using the OPTIONAL **type** node. The value MUST be the name of a resource type defined within the root-level resourceTypes node or in a library. Resource type definitions do not apply to existing nested resources. Similarly, a method can specify one or more traits it inherits using the OPTIONAL **is** node. The value of a trait is an array of any number of elements where each MUST be the name of a trait defined within the root-level traits node or in a library. A trait can also be applied to a resource by using the **is** node. Using this node is equivalent to applying the trait to all methods for that resource, whether declared explicitly in the resource definition or inherited from a resource type. A trait is applied to a method in left-to-right order, according to the traits defined in the **is** node. Trait definitions do not apply to nested resources. From 5f2fdfa9580b92d14bfc56a863b10834709b1509 Mon Sep 17 00:00:00 2001 From: Jonathan Stoikovitch Date: Tue, 20 Aug 2019 16:51:07 -0700 Subject: [PATCH 08/49] removing confusing sentence above Object Type example --- 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 0c8a8efa..81c19b86 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -580,7 +580,7 @@ All types that have the built-in object base type in its inheritance tree MAY us | discriminator? | Determines the concrete type of an individual object at runtime when, for example, payloads contain ambiguous types due to unions or inheritance. The value must match the name of one of the declared `properties` of a type. Unsupported practices are inline type declarations and [using `discriminator`](#using-discriminator) with non-scalar properties. | discriminatorValue? | Identifies the declaring type. Requires including a `discriminator` facet in the type declaration. A valid value is an actual value that might identify the type of an individual object and is unique in the hierarchy of the type. Inline type declarations are not supported.

**Default:** The name of the type -An object type is created by explicit inheritance from the built-in type object: +Example: ```yaml #%RAML 1.0 From dcb3f7f296e2263700537b56ae5ac8f3721e64d0 Mon Sep 17 00:00:00 2001 From: Jonathan Stoikovitch Date: Mon, 16 Sep 2019 15:10:12 -0700 Subject: [PATCH 09/49] add missing '?' after 'usage' node under Libraries list of allowed nodes --- 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 81c19b86..2fd3396f 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -3210,7 +3210,7 @@ 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). +| 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. From 35b9df46cf2837c4e5d4a5c3959446765474d267 Mon Sep 17 00:00:00 2001 From: Jonathan Stoikovitch Date: Tue, 1 Oct 2019 21:52:22 -0700 Subject: [PATCH 10/49] specify that !include cannot be used in type expressions and multiple inheritance --- 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 2fd3396f..da0b0df5 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -3034,7 +3034,7 @@ RAML provides several mechanisms to help modularize the ecosystem of an API spec ### 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. +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. Therefor, the !include tag cannot be used in any type expression or multiple inheritance. 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. From 8770881a95d42298a19cad44996a617c36817f0c Mon Sep 17 00:00:00 2001 From: Jonathan Stoikovitch Date: Thu, 16 Jan 2020 14:49:40 -0800 Subject: [PATCH 11/49] Fixing #725 --- 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 da0b0df5..274428a8 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -59,7 +59,7 @@ Throughout this specification, **Markdown** means [GitHub-Flavored Markdown](htt - [Default Media Types](#default-media-types) - [Default Security](#default-security) - [RAML Data Types](#raml-data-types) - - [Introduction](#introduction) + - [Introduction](#introduction-1) - [Overview](#overview) - [Defining Types](#defining-types) - [Type Declarations](#type-declarations) From 7e7aa4f3e706c44be75ab673ad805a7731000be0 Mon Sep 17 00:00:00 2001 From: Jonathan Stoikovitch Date: Mon, 15 Jun 2020 20:01:35 -0700 Subject: [PATCH 12/49] Fixed a minor typo in one of the RAML snippets --- versions/raml-10/raml-10.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 274428a8..ac32ebe8 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1198,7 +1198,7 @@ The following example shows a valid declaration. types: Person: type: !include person.json - description: this is a schema describing person + description: this is a schema describing a person ``` The following example shows an invalid declaration of a type that inherits the characteristics of a JSON schema and adds additional properties. @@ -1217,7 +1217,7 @@ Another invalid case is shown in the following example of the type `Person` bein types: Person: type: !include person.json - description: this is a schema describing person + description: this is a schema describing a person Board: properties: members: Person[] # invalid use of type expression '[]' and as a property type From 56180bde98b7f8033bb43def7e95de0dd71566ed Mon Sep 17 00:00:00 2001 From: Jonathan Stoikovitch Date: Fri, 14 Aug 2020 17:57:15 -0700 Subject: [PATCH 13/49] Closes #707 --- versions/raml-10/raml-10.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index db29ef45..44b98430 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -33,7 +33,7 @@ In this specification, **API definition** means an API using this specification. A **resource** is the conceptual mapping to an entity or set of entities. -A trailing question mark, for example **description?**, indicates an optional property. +A trailing question mark in key names MAY denote an optional key. ### Template URI @@ -598,7 +598,7 @@ types: Properties of object types are defined using the OPTIONAL **properties** facet. The RAML Specification calls the value of the "properties" facet a "properties declaration". The properties declaration is a map of keys and values. The keys are valid property names for declaring a type instance. The values are either a name of a type or an inline type declaration. -The properties declaration can specify whether a property is required or optional. +The properties declaration can specify whether a property is required or optional. Alternatively, a trailing question mark (`?`) in the key name MAY be used to indicate that said property is optional. | Facet | Description | |:----------|:----------| @@ -633,7 +633,7 @@ types: # required: false ``` -When the `required` facet on a property is specified explicitly in a type declaration, any question mark in its property name is treated as part of the property name rather than as an indicator that the property is optional. +When the `required` facet on a property is specified explicitly in a type declaration, any question mark in its property name MUST be treated as part of the property name rather than as an indicator that the property is optional. For example, in @@ -1247,7 +1247,7 @@ When referencing an inner element of a schema, a RAML processor MUST validate an Facets express various additional restrictions beyond those which types impose on their instances, such as the optional `minimum` and `maximum` facets for numbers, or the `enum` facet for scalars. In addition to the built-in facets, RAML provides a way to declare user-defined facets for any data type. -The user-defined facet is declared using the OPTIONAL `facets` facet in a type declaration. The value of the `facets` facet is a map. The key names the user-defined facet. The corresponding value defines the concrete value that the respective facet can take. The syntax of a [property declaration](#property-declarations) and user-defined facet declaration are the same. A facet restricts instances of a subtype, not its type, based on the concrete value defined in the facet declaration. +The user-defined facet is declared using the OPTIONAL `facets` facet in a type declaration. The value of the `facets` facet is a [properties declaration](#property-declarations) object, as is the value of the properties object of a type declaration. Each property in this declaration object is referred to as a **user-defined facet declaration**. Each property name specifies a user-defined facet name. A trailing question mark (`?`) in a property name MAY be used to indicate that said user-defined facet is optional. Each property value specifies the user-defined facet value type as the name of a type or an inline type declaration. Facet names MUST NOT begin with open parenthesis, to disambiguate the names from annotations. User-defined facet names on a type MUST NOT match built-in facets on that type, nor facet names of any ancestor type in the inheritance chain of the type. @@ -1992,7 +1992,7 @@ types: #### Query Parameters in a Query String -The **queryParameters** node specifies the set of query parameters from which the query string is composed. When applying the restrictions defined by the API, processors MUST regard the query string as a set of query parameters according to the URL encoding format. The value of the queryParameters node is a [properties declaration](#property-declarations) object, as is the value of the properties object of a type declaration. Each property in this declaration object is referred to as a **query parameter declaration**. Each property name specifies an allowed query parameter name. Each property value specifies the query parameter value type as the name of a type or an inline type declaration. +The **queryParameters** node specifies the set of query parameters from which the query string is composed. When applying the restrictions defined by the API, processors MUST regard the query string as a set of query parameters according to the URL encoding format. The value of the queryParameters node is a [properties declaration](#property-declarations) object, as is the value of the properties object of a type declaration. Each property in this declaration object is referred to as a **query parameter declaration**. Each property name specifies an allowed query parameter name. A trailing question mark (`?`) in a property name MAY be used to indicate that said query parameter is optional. Each property value specifies the query parameter value type as the name of a type or an inline type declaration. If a query parameter declaration specifies an array type for the value of the query parameter, processors MUST allow multiple instances of that query parameter in the request or response. In this case, the type of the elements of the array MUST be applied as the type of the value of query parameter instances. From fa7ee2c20a94ee9526730d7a9b502df18df8331d Mon Sep 17 00:00:00 2001 From: Jonathan Stoikovitch Date: Mon, 17 Aug 2020 09:40:20 -0700 Subject: [PATCH 14/49] Closes #${branch:0:3} --- versions/raml-10/raml-10.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index db29ef45..cc9468b4 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1036,6 +1036,8 @@ types: In RAML, the type `nil` is a scalar type that allows only nil data values. Specifically, in YAML it allows only YAML's `null` (or its equivalent representations, such as `~`), in JSON it allows only JSON's `null`, and in XML it allows only XML's `xsi:nil`. In headers, URI parameters, and query parameters, the `nil` type only allows the string value "nil" (case-sensitive); and in turn an instance having the string value "nil" (case-sensitive), when described with the `nil` type, deserializes to a nil value. +Using the type `nil` in a union, makes a type definition nilable, meaning that any instance of that union MAY be a nil data value. When such union is composed of only one type in addition to `| nil`, a trailing question mark `?` in lieu of such union is equivalent. The use of that equivalent alternative syntax SHALL be restricted to [scalar types](#scalar-types) and references to user-defined types, and SHALL NOT be used in [type expressions](#type-expressions). + In the following example, the type is an object and has two required properties, `name` and `comment`, both defaulting to type `string`. In `example`, `name` is assigned a string value, but comment is nil and this is _not_ allowed because RAML expects a string. ```yaml @@ -1073,7 +1075,7 @@ types: properties: name: comment: nil | string # equivalent to -> - # comment: string? + # comment: string? example: name: Fred comment: # Providing a value or not providing a value here is allowed. @@ -1081,6 +1083,8 @@ types: Declaring the type of a property to be `nil` represents the lack of a value in a type instance. In a RAML context that requires *values* of type `nil` (vs just type declarations), the usual YAML `null` is used, e.g. when the type is `nil | number` you may use `enum: [ 1, 2, ~ ]` or more explicitly/verbosely `enum: [ 1, 2, !!null "" ]`; in non-inline notation you can just omit the value completely, of course. +Nilable values are not the same as optional properties, e.g. to have a `comment` property that is optional and which can also have a `nil` value, you could define it as `comment?: string?` or `comment?: nil | string`. + #### Union Type A union type is used to allow instances of data to be described by any of several types. A union type is declared via a type expression that combines 2 or more types delimited by pipe (`|`) symbols; these combined types are referred to as the union type's super types. In the following example, instances of the `Device` type may be described by either the `Phone` type or the `Notebook` type: From 3afe3249292db1f7ea3a821a20baf1f7d2e18526 Mon Sep 17 00:00:00 2001 From: Jonathan Stoikovitch Date: Mon, 17 Aug 2020 09:40:27 -0700 Subject: [PATCH 15/49] Closes #709 --- versions/raml-10/raml-10.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index db29ef45..ec65afcd 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1484,7 +1484,7 @@ title: My API With Types ### Defining Examples in RAML -It is highly RECOMMENDED that API documentation include a rich selection of examples. RAML supports either the definition of multiple examples or a single one for any given instance of a type declaration. +It is highly RECOMMENDED that API documentation include a rich selection of examples. RAML supports either the definition of multiple examples or a single one for any given instance of a type declaration. In addition to YAML by default, processors SHOULD support JSON and XML representations of examples. Processors MAY support additional formats. Note that type definition is agnostic to example encoding such that, e.g. examples in YAML will work for JSON or XML, and in reverse for any chosen combination of those three supported encodings. #### Multiple Examples @@ -1526,7 +1526,7 @@ The map can contain the following additional facets: | description? | A substantial, human-friendly description for an example. Its value is a string and 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. | value | The actual example of a type instance. -| strict? | Validates the example against any type declaration (the default), or not. Set this to false avoid validation. +| strict? | Validates the example against any type declaration (the default). Set this to false to prevent validation. For example: From 71e6a4a6469afdc3c6f5f4e28d5b52a4fb296321 Mon Sep 17 00:00:00 2001 From: Jonathan Stoikovitch Date: Mon, 17 Aug 2020 09:40:31 -0700 Subject: [PATCH 16/49] Closes #710 --- versions/raml-10/raml-10.md | 16 +++++----------- 1 file changed, 5 insertions(+), 11 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index db29ef45..daee92d2 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1277,25 +1277,19 @@ User-defined facets by definition are not built into this RAML specification, an A RAML processor must be able to determine the default type of a type declaration by using the following rules: -* If, and only if, a type declaration contains a `properties` facet, then the default type is `object`. The following snippet exemplifies this rule: +* If, and only if, a type declaration contains a facet that is unique to that type, then its default type is inferred to be the only one with support for the facet being used. -```yaml -types: - Person: - type: object - properties: -``` - -This rule can also be written as follows: +For example, if a type declaration contains a `properties` facet, its default type is `object`. The following snippet exemplifies this rule: ```yaml types: Person: - # default type is `object`, no need to explicitly define it + # default type is "object" because "properties" is unique to that type + # i.e. no need to explicitly define it, "type: object" is inferred properties: ``` -* If, and only if, a type declaration contains neither a `properties` facet nor a `type` or `schema` facet, then the default type is `string`. The following snippet exemplifies this rule: +* If, and only if, a type declaration contains neither a facet that is unique to a given type as described in the previous rule above, nor a `type` or `schema` facet, then the default type is `string`. The following snippet exemplifies this rule: ```yaml types: From 761a190b1f545fe7c309dc72f5d7cc14fca38d2f Mon Sep 17 00:00:00 2001 From: Jonathan Stoikovitch Date: Mon, 17 Aug 2020 09:40:36 -0700 Subject: [PATCH 17/49] Closes #711 --- versions/raml-10/raml-10.md | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index db29ef45..df4ab38f 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1170,6 +1170,42 @@ types: HomeAnimal: [ HasHome | IsOnFarm , Dog | Cat | Parrot ] ``` +A union type MAY use facets defined by any of its member types as long as all member types in the union accept those facets. + +For example: + +```yaml +types: + Foo: number + Bar: integer + FooBar: + type: Foo | Bar + minimum: 1 # valid because both "Foo" (number) and "Bar" (integer) all accept "minimum" +``` + +```yaml +types: + Foo: number + Bar: integer + Qux: string + FooBarQux: + type: Foo | Bar | Qux + minimum: 1 # invalid because "Qux" (string) does not accept the "minimum" facet +``` + +```yaml +types: + Foo: number + Bar: integer + Qux: + type: string + facets: + minimum: number + FooBarQux: + type: Foo | Bar | Qux + minimum: 1 # valid because "Qux" (string) has a user-defined facet "minimum" +``` + #### Using XML and JSON Schema RAML allows the use of XML and JSON schemas to describe the body of an API request or response by integrating the schemas into its data type system. From 882e633fdc163ba4add30fd37e4c40d3dd1753e4 Mon Sep 17 00:00:00 2001 From: Jonathan Stoikovitch Date: Mon, 17 Aug 2020 09:40:40 -0700 Subject: [PATCH 18/49] Closes #712 --- versions/raml-10/raml-10.md | 42 +++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index db29ef45..b8da20a6 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1169,6 +1169,48 @@ If you are extending from two union types a processor MUST perform validations f types: HomeAnimal: [ HasHome | IsOnFarm , Dog | Cat | Parrot ] ``` +If a union type contains a facet with an `enum`, every value of that `enum` MUST meet all restrictions associated with at least one of the super types. Here is an example: + +This is valid: +``` +type: number | boolean +enum: [1, true, 2] +``` + +This is invalid: +``` +type: number | boolean +enum: [1, true, 2, "hello"] +``` + +Recall that types in this case can be built-in data types, such as number or boolean, but also custom user-defined types such as unions or complex types with multiple properties. Imagine a more complex example: + +```yaml +#%RAML 1.0 +title: Scheduling API + +types: + CustomDates: + enum: [Monday12, Tuesday18, Wednesday7] + PossibleMeetingDates: + properties: + daysAllowed: + type: CustomDates | date-only + enum: [Monday12, Wednesday7, 2020-02-08, 2020-02-09] + PossibleVacationDates: + properties: + daysAllowed: + type: datetime-only + enum: [2020-02-01T00:00:00, 2019-02-22T00:00:00] + ScheduledDays: + type: PossibleMeetingDates | PossibleVacationDates + properties: + daysAllowed: + enum: [2020-02-01T00:00:00, Monday12] # VALID + # enum: [Tuesday123] # INVALID: "Tuesday123" does not match any of the super-types' enum values + # enum: [Tuesday18] # INVALID: although "Tuesday18" is an (allowed) enum value of "CustomDates", it is not listed in "PossibleMeetingDates" > "daysAllowed" `enum`, which is more restrictive + # enum: [2020-02-01T00:00:00, 2020-02-18] # INVALID +``` #### Using XML and JSON Schema From d369ea70a2c0783c43e31de599e6b7f5addbd31c Mon Sep 17 00:00:00 2001 From: Jonathan Stoikovitch Date: Mon, 17 Aug 2020 09:40:44 -0700 Subject: [PATCH 19/49] Closes #714 --- 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 db29ef45..9bbe3a19 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -914,7 +914,7 @@ A JSON string with the following additional facets: | Facet | Description | |:--------|:------------| -| pattern? | Regular expression that this string SHOULD match. +| pattern? | Regular expression that this string MUST match. | minLength? | Minimum length of the string. Value MUST be equal to or greater than 0.

**Default:** `0` | maxLength? | Maximum length of the string. Value MUST be equal to or greater than 0.

**Default:** `2147483647` From c4586370baa5ec5445bbd0b01fd75012ee4e9acc Mon Sep 17 00:00:00 2001 From: Jonathan Stoikovitch Date: Mon, 17 Aug 2020 09:40:48 -0700 Subject: [PATCH 20/49] Closes #715 --- 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 db29ef45..21798265 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -176,7 +176,7 @@ This document is organized as follows: This specification uses [YAML 1.2](http://www.yaml.org/spec/1.2/spec.html) as its underlying format. YAML is a human-readable data format that aligns well with the design goals of this specification. As in YAML, all nodes such as keys, values, and tags, are case-sensitive. -RAML API definitions are YAML 1.2-compliant documents that begin with a REQUIRED YAML-comment line that indicates the RAML version, as follows: +RAML API definitions MUST be YAML 1.2-compliant documents that begin with a REQUIRED YAML-comment line that indicates the RAML version, as follows: ```yaml #%RAML 1.0 From d8f39fe2e827c6c9c90d45a43497c850f11e75eb Mon Sep 17 00:00:00 2001 From: Jonathan Stoikovitch Date: Mon, 17 Aug 2020 09:40:52 -0700 Subject: [PATCH 21/49] Closes #716 --- versions/raml-10/raml-10.md | 28 +++++++++++++++------------- 1 file changed, 15 insertions(+), 13 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index db29ef45..c4de0d2b 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -215,10 +215,9 @@ resourceTypes: collection: !include types/collection.raml traits: securedBy: [ oauth_2_0 ] -/search: - /code: - type: collection - get: +/users: + type: collection + get: ``` The following table enumerates the possible nodes at the root of a RAML document: @@ -309,21 +308,23 @@ baseUriParameters: description: The name of the bucket ``` -When the base URI ends in one or more slashes (`/`), those trailing slashes are omitted in the absolute paths for the resources using that base URI. For example, in the following snippet, the absolute paths for the resources are `http://api.test.com/common/users` and `http://api.test.com/common/users/groups`. +When the base URI ends in one or more slashes (`/`), those trailing slashes are omitted in the absolute paths for the resources using that base URI. For example, in the following snippet, the absolute paths for the resources are `http://api.test.com/common/users/:userId` and `http://api.test.com/common/users/:userId/groups`. ```yaml baseUri: http://api.test.com/common/ /users: - /groups: + /{userId}: + /groups: ``` -In the following, more complicated example with consecutive slashes in multiple places, only trailing slashes in the base URI are collapsed, leading to these absolute paths to resources: `//api.test.com//common/`, `//api.test.com//common//users/`, and `//api.test.com//common//users//groups//`. +In the following, more complicated example with consecutive slashes in multiple places, only trailing slashes in the base URI are collapsed, leading to these absolute paths to resources: `//api.test.com//common/`, `//api.test.com//common//users//:userId//`, and `//api.test.com//common//users//:userId//groups//`. ```yaml baseUri: //api.test.com//common// /: /users/: - /groups//: + /{userId}/: + /groups//: ``` ### Protocols @@ -362,7 +363,7 @@ title: New API mediaType: [ application/json, application/xml ] ``` -Explicitly defining a `mediaType` node for a [body](#bodies) of an API request or response overrides the default media type, as shown in the following example. The resource `/list` returns a `Person[]` body represented as either JSON or XML. The resource `/send` overrides the default media type by explicitly defining an `application/json` node. Therefore, the resource `/send` returns only a JSON-formatted body. +Explicitly defining a `mediaType` node for a [body](#bodies) of an API request or response overrides the default media type, as shown in the following example. The resource `/people` returns a `Person[]` body represented as either JSON or XML. The resource `/messages` overrides the default media type by explicitly defining an `application/json` node. Therefore, the resource `/messages` returns only a JSON-formatted body. ```yaml #%RAML 1.0 @@ -371,12 +372,12 @@ mediaType: [ application/json, application/xml ] types: Person: Another: -/list: +/people: get: responses: 200: body: Person[] -/send: +/messages: post: body: application/json: @@ -1182,7 +1183,7 @@ types: ``` ```yaml -/person: +/people/{personId}: get: responses: 200: @@ -1561,7 +1562,7 @@ types: name: string address?: string value?: string -/organization: +/organizations: post: headers: UserID: @@ -1575,6 +1576,7 @@ types: value: # needs to be declared since instance contains a 'value' property name: Doe Enterprise value: Silver +/organizations/{orgId} get: description: Returns an organization entity. responses: From 900c2bb0fadbb487876973daef9960d32f4d44ff Mon Sep 17 00:00:00 2001 From: Jonathan Stoikovitch Date: Mon, 17 Aug 2020 09:40:56 -0700 Subject: [PATCH 22/49] Closes #718 --- versions/raml-10/raml-10.md | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index db29ef45..dc588205 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -3074,9 +3074,15 @@ A file to be included MAY begin with a RAML fragment identifier line, which cons | 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. +In addition to any nodes allowed in any of the "Relevant RAML Specification Sections" above, the following OPTIONAL node is allowed: -The following example shows a RAML fragment file that defines a resource type and a file that includes this fragment file. +|Allowed Node | Description | +|:------------|:------------| +| uses? | Imported external [libraries](#libraries) for use within the RAML typed fragment. | + +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 and any `uses` node 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 typed fragment file. ```yaml #%RAML 1.0 ResourceType @@ -3206,11 +3212,11 @@ traits: 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. +In addition to any nodes allowed at the root of [RAML typed fragments](#typed-fragments), RAML libraries allow the following optional nodes: |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. +| types?
schemas?
resourceTypes?
traits?
securitySchemes?
annotationTypes?
(<annotationName>)? | 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. @@ -3239,11 +3245,11 @@ resourceTypes: #### 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. +Any number of libraries can be applied by using the OPTIONAL **uses** node at the root of a RAML or RAML typed 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 a document that applies a library, the data types, resource types, traits, security schemes, and annotation types in the library become available within the document. The assets in the library are referenced within the document 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. The library name defines a namespace for the library nodes within the context in which 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. +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 typed 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 typed 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. From 1d55da4911f95672fdb2c2580785fca1cd888205 Mon Sep 17 00:00:00 2001 From: Jonathan Stoikovitch Date: Mon, 17 Aug 2020 09:41:00 -0700 Subject: [PATCH 23/49] Closes #719 --- 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 db29ef45..7f933cbd 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -3314,7 +3314,7 @@ API definitions might need to be extended in a variety of ways for different nee 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. +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. The resolution of paths in an overlay or extension document, such as those for `!include` tags or libraries, MUST be relative to the document from which the reference is being made, as opposed to the API root document. 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. From 271b9cd95d662bc483cd1a40c289cf5278e2943d Mon Sep 17 00:00:00 2001 From: Jonathan Stoikovitch Date: Mon, 17 Aug 2020 09:41:04 -0700 Subject: [PATCH 24/49] Closes #720 --- versions/raml-10/raml-10.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index db29ef45..b5efa5ad 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1238,10 +1238,12 @@ Sometimes it is necessary to refer to an element defined in a schema. RAML suppo type: !include elements.xsd#Foo ``` -When referencing an inner element of a schema, a RAML processor MUST validate an instance against that particular element. The RAML specification supports referencing any inner elements in JSON schemas that are valid schemas, any globally defined elements, and complex types in XML schemas. There are only a few restrictions: +When referencing an inner element of a JSON or XML schema, a RAML processor MUST validate an instance against that particular element. The RAML specification supports referencing any inner elements in JSON schemas that are valid schemas, any globally defined elements, and complex types in XML schemas. There are only a few restrictions: * Validation of any XML or JSON instance against inner elements follows the same restrictions as the validation against a regular XML or JSON schema. * Referencing complex types inside an XSD is valid to determine the structure of an XML instance, but since complex types do not define a name for the top-level XML element, these types cannot be used for serializing an XML instance. +* References pointing to inner elements of JSON schemas MUST be valid JSON Pointers as defined in [RFC6901](https://tools.ietf.org/html/rfc6901). + ### User-defined Facets From aca27da81be9dcd2f7616aa8a4b661c64a33f1f8 Mon Sep 17 00:00:00 2001 From: Jonathan Stoikovitch Date: Mon, 17 Aug 2020 09:41:08 -0700 Subject: [PATCH 25/49] Closes #724 --- 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 db29ef45..61012a3d 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -2200,7 +2200,7 @@ resourceTypes: A resource can specify the resource type from which it is derived using the OPTIONAL **type** node. The value MUST be the name of a resource type defined within the root-level resourceTypes node or in a library. Resource type definitions do not apply to existing nested resources. -Similarly, a method can specify one or more traits it inherits using the OPTIONAL **is** node. The value of a trait is an array of any number of elements where each MUST be the name of a trait defined within the root-level traits node or in a library. A trait can also be applied to a resource by using the **is** node. Using this node is equivalent to applying the trait to all methods for that resource, whether declared explicitly in the resource definition or inherited from a resource type. A trait is applied to a method in left-to-right order, according to the traits defined in the **is** node. Trait definitions do not apply to nested resources. +Similarly, a method can specify one or more traits it inherits using the OPTIONAL **is** node. The value of a trait MUST be an array of any number of elements where each MUST be the name of a trait defined within the root-level traits node or in a library. A trait can also be applied to a resource by using the **is** node. Using this node is equivalent to applying the trait to all methods for that resource, whether declared explicitly in the resource definition or inherited from a resource type. A trait is applied to a method in left-to-right order, according to the traits defined in the **is** node. Trait definitions do not apply to nested resources. The following example illustrates the application of resource types and traits. From 9cf0f255d45d0d71c939cdcce13fc859660ca3d1 Mon Sep 17 00:00:00 2001 From: Jonathan Stoikovitch Date: Mon, 17 Aug 2020 09:41:12 -0700 Subject: [PATCH 26/49] Closes #727 --- versions/raml-10/raml-10.md | 38 ++++++++++++++++++++++++++++++++++++- 1 file changed, 37 insertions(+), 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index db29ef45..88e4318d 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -3065,7 +3065,7 @@ A file to be included MAY begin with a RAML fragment identifier line, which cons |:-------------------|:------------| :-----------------------------------| | 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](#defining-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) +| NamedExample | A declaration of the examples facet, whose keys are names of examples and whose values describe each of the examples | [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) @@ -3128,6 +3128,42 @@ resourceTypes: description: All products ``` +The following example shows a RAML fragment file that defines multiple examples and a file that includes this fragment file. + +```yaml +#%RAML 1.0 NamedExample + +#This file is located at examples/paging-examples.raml + +onlyStart: + displayName: Only Start + value: + start: 2 +startAndPageSize: + description: Contains start and page size + value: + start: 3 + page-size: 20 +``` + +```yaml +#%RAML 1.0 +title: Products API + +types: + paging: + properties: + start?: number + page-size?: number + +/products: + description: All products + get: + queryString: + type: paging + examples: !include examples/paging-examples.raml +``` + #### 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: From bbd0115c824514984a2186344dbb4d7483e16b49 Mon Sep 17 00:00:00 2001 From: Jonathan Stoikovitch Date: Mon, 17 Aug 2020 09:41:16 -0700 Subject: [PATCH 27/49] Closes #728 --- versions/raml-10/raml-10.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index db29ef45..77c2085f 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -987,7 +987,11 @@ The following date type representations MUST be supported: | datetime-only | Combined date-only and time-only with a separator of "T", namely yyyy-mm-ddThh:mm:ss\[.ff...\]. Does not support a time zone offset. | datetime | A timestamp in one of the following formats: if the _format_ is omitted or set to `rfc3339`, uses the "date-time" notation of [RFC3339](http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14); if _format_ is set to `rfc2616`, uses the format defined in [RFC2616](https://www.ietf.org/rfc/rfc2616.txt). -The additional facet _format_ MUST be available only when the type equals _datetime_, and the value MUST be either `rfc3339` or `rfc2616`. Any other values are invalid. +The additional facet `format` MUST be available only when the type equals `datetime`: + +| Facet | Description | +|:-----|:------------| +| format? | The format of the value of a type `datetime`. The value MUST be either `rfc3339` or `rfc2616`. Any other values are invalid. ```yaml types: From a6079721d11468cc3d8bdc141abd9c00b270d3e6 Mon Sep 17 00:00:00 2001 From: Jonathan Stoikovitch Date: Mon, 17 Aug 2020 09:41:20 -0700 Subject: [PATCH 28/49] Closes #730 --- 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 db29ef45..4bc0260d 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -2331,7 +2331,7 @@ traits: example: <>=h8duh3uhhu38 # e.g. get=h8duh3uhhu38 ``` -Parameters cannot be used within an !include tag specification of the include file location. +Parameters cannot be used within any file location used in the context of [modularization](https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md#modularization), that is any file location defined in the `!include` tag or as value of any of the `uses` and `extends` nodes. ### Declaring HTTP Methods as Optional From e8f170694fba9f3d576b83b41017a4ba0aaa55e0 Mon Sep 17 00:00:00 2001 From: Jonathan Stoikovitch Date: Tue, 18 Aug 2020 10:19:22 -0700 Subject: [PATCH 29/49] Adding missing `:` to example --- 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 c4de0d2b..920c5904 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1576,7 +1576,7 @@ types: value: # needs to be declared since instance contains a 'value' property name: Doe Enterprise value: Silver -/organizations/{orgId} +/organizations/{orgId}: get: description: Returns an organization entity. responses: From 8a45c85df46e931b07476490888a9e650688d64c Mon Sep 17 00:00:00 2001 From: Jonathan Stoikovitch Date: Mon, 21 Sep 2020 12:08:37 -0700 Subject: [PATCH 30/49] Fixed typo in 'Resource Type and Trait Parameters' (Partially fixes #729) --- 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 ac32ebe8..b05e9f86 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -2268,7 +2268,7 @@ A processing application MUST set the value of `<>` to the concate For example, applying a resource type or trait to a resource `/users` nested in a resource `/{groupId}` nested in a root-level resource `/groups` sets the value of the resourcePath parameter to "`/groups/{groupId}/users`". Applying a resource type or trait to a resource `/jobs/{jobId}` sets the value of the resourcePathName parameter to "jobs". -When setting resourcePath and resourcePathName, processing applications MUST also omit any ext parameter and its parametrizing brackets ("{" and "}") found in the resource URI. For example, applying a resource type or trait to a root-level resource `/bom/{itemId}{ext}` sets the value of resourcePathName and resourcePath parameters to "`/bom/{itemId}`" and "bom", respectively. +When setting resourcePath and resourcePathName, processing applications MUST also omit any ext parameter and its parametrizing brackets ("{" and "}") found in the resource URI. For example, applying a resource type or trait to a root-level resource `/bom/{itemId}{ext}` sets the value of resourcePath and resourcePathName parameters to "`/bom/{itemId}`" and "`bom`", respectively. In trait declarations, **methodName** is a reserved parameter. From b76d1d04bcab77c86e0a8d18ff40ea7c9eb6373d Mon Sep 17 00:00:00 2001 From: Jonathan Stoikovitch Date: Mon, 21 Sep 2020 12:13:51 -0700 Subject: [PATCH 31/49] Fixed incoherent facet values in String type example (Partially fixes #729) --- versions/raml-10/raml-10.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index b05e9f86..631959f5 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -922,11 +922,11 @@ Example: ```yaml types: - Email: + EmailAddress: type: string - minLength: 2 - maxLength: 6 - pattern: ^note\d+$ + pattern: ^.+@.+\..+$ + minLength: 3 + maxLength: 320 ``` ##### Number From 29ac49fbc501441b9ed37507e0c066f8b74003ad Mon Sep 17 00:00:00 2001 From: Jonathan Stoikovitch Date: Fri, 13 Nov 2020 10:38:06 -0800 Subject: [PATCH 32/49] Fixed typo 'mixing pattern' to read 'mixin pattern' --- 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 631959f5..ee5c6bcf 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -2131,7 +2131,7 @@ Moreover, resource and method declarations are frequently repetitive. For exampl A resource type, like a resource, can specify security schemes, methods, and other nodes. A resource that uses a resource type inherits its nodes. A resource type can also use, and thus inherit from, another resource type. Resource types and resources are related through an inheritance chain pattern. A resource type definition MUST NOT incorporate nested resources. A resource type definition cannot be used to generate nested resources when the definition is applied to a resource. A resource type definition does not apply to its own existing nested resources. -A trait, like a method, can provide method-level nodes such as description, headers, query string parameters, and responses. Methods that use one or more traits inherit nodes of those traits. A resource and resource type can also use, and thus inherit from, one or more traits, which then apply to all methods of the resource and resource type. Traits are related to methods through a mixing pattern. +A trait, like a method, can provide method-level nodes such as description, headers, query string parameters, and responses. Methods that use one or more traits inherit nodes of those traits. A resource and resource type can also use, and thus inherit from, one or more traits, which then apply to all methods of the resource and resource type. Traits are related to methods through a mixin pattern. ### Declaring Resource Types and Traits From 034e1553c8d47d962381e1336a05a0dd9b1db511 Mon Sep 17 00:00:00 2001 From: Jonathan Stoikovitch Date: Wed, 23 Dec 2020 18:34:55 -0800 Subject: [PATCH 33/49] Apply suggestions from code review Co-authored-by: priyaayyar <50642006+priyaayyar@users.noreply.github.com> --- versions/raml-10/raml-10.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 920c5904..66495e4d 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -308,7 +308,7 @@ baseUriParameters: description: The name of the bucket ``` -When the base URI ends in one or more slashes (`/`), those trailing slashes are omitted in the absolute paths for the resources using that base URI. For example, in the following snippet, the absolute paths for the resources are `http://api.test.com/common/users/:userId` and `http://api.test.com/common/users/:userId/groups`. +When the base URI ends in one or more slashes (`/`), the trailing slashes are omitted in the absolute paths for the resources using that base URI. For example, in the following snippet, the absolute paths for the resources are `http://api.test.com/common/users/:userId` and `http://api.test.com/common/users/:userId/groups`. ```yaml baseUri: http://api.test.com/common/ @@ -363,7 +363,7 @@ title: New API mediaType: [ application/json, application/xml ] ``` -Explicitly defining a `mediaType` node for a [body](#bodies) of an API request or response overrides the default media type, as shown in the following example. The resource `/people` returns a `Person[]` body represented as either JSON or XML. The resource `/messages` overrides the default media type by explicitly defining an `application/json` node. Therefore, the resource `/messages` returns only a JSON-formatted body. +Explicitly defining a `mediaType` node for a [body](#bodies) of an API request or response overrides the default media type, as shown in the following example. The resource `/people` returns a `Person[]` body in either JSON or XML. The resource `/messages` overrides the default media type by explicitly defining an `application/json` node. Therefore, the resource `/messages` returns only a JSON-formatted body. ```yaml #%RAML 1.0 From 82d10b8b008c7df21bffdd7d5a45aa27518891dc Mon Sep 17 00:00:00 2001 From: Jonathan Stoikovitch Date: Wed, 23 Dec 2020 18:40:16 -0800 Subject: [PATCH 34/49] Apply suggestions from code review Co-authored-by: priyaayyar <50642006+priyaayyar@users.noreply.github.com> --- versions/raml-10/raml-10.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index b8da20a6..aa2b1253 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1171,19 +1171,19 @@ types: ``` If a union type contains a facet with an `enum`, every value of that `enum` MUST meet all restrictions associated with at least one of the super types. Here is an example: -This is valid: +The following example illustrates a valid expression: ``` type: number | boolean enum: [1, true, 2] ``` -This is invalid: +The following example illustrates an invalid expression: ``` type: number | boolean enum: [1, true, 2, "hello"] ``` -Recall that types in this case can be built-in data types, such as number or boolean, but also custom user-defined types such as unions or complex types with multiple properties. Imagine a more complex example: +Note that types, in this case, can be built-in data types, such as numbers or boolean, or can be custom user-defined types, such as unions or complex types with multiple properties. Imagine a more complex example: ```yaml #%RAML 1.0 From f1319f6c8f4a28aaf4d4fe8edd7afd03b5aa229a Mon Sep 17 00:00:00 2001 From: Jonathan Stoikovitch Date: Wed, 23 Dec 2020 18:44:31 -0800 Subject: [PATCH 35/49] Apply suggestions from code review Co-authored-by: priyaayyar <50642006+priyaayyar@users.noreply.github.com> --- versions/raml-10/raml-10.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index daee92d2..a12f40fb 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1277,7 +1277,7 @@ User-defined facets by definition are not built into this RAML specification, an A RAML processor must be able to determine the default type of a type declaration by using the following rules: -* If, and only if, a type declaration contains a facet that is unique to that type, then its default type is inferred to be the only one with support for the facet being used. +* If, and only if, a type declaration contains a facet that is unique to that type, its default type is then inferred to be the only one with support for the facet being used. For example, if a type declaration contains a `properties` facet, its default type is `object`. The following snippet exemplifies this rule: @@ -1289,7 +1289,7 @@ types: properties: ``` -* If, and only if, a type declaration contains neither a facet that is unique to a given type as described in the previous rule above, nor a `type` or `schema` facet, then the default type is `string`. The following snippet exemplifies this rule: +* If, and only if, a type declaration contains a facet that is neither unique to a given type, as described in the previous rule above, nor a `type` or `schema` facet, then the default type is `string`. The following snippet exemplifies this rule: ```yaml types: From 18fde997b39a763f6a4aacbba30c90d996eb3f6f Mon Sep 17 00:00:00 2001 From: Jonathan Stoikovitch Date: Wed, 23 Dec 2020 18:48:53 -0800 Subject: [PATCH 36/49] Apply suggestions from code review Co-authored-by: Duke --- versions/raml-10/raml-10.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index cc9468b4..a7578231 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1036,7 +1036,7 @@ types: In RAML, the type `nil` is a scalar type that allows only nil data values. Specifically, in YAML it allows only YAML's `null` (or its equivalent representations, such as `~`), in JSON it allows only JSON's `null`, and in XML it allows only XML's `xsi:nil`. In headers, URI parameters, and query parameters, the `nil` type only allows the string value "nil" (case-sensitive); and in turn an instance having the string value "nil" (case-sensitive), when described with the `nil` type, deserializes to a nil value. -Using the type `nil` in a union, makes a type definition nilable, meaning that any instance of that union MAY be a nil data value. When such union is composed of only one type in addition to `| nil`, a trailing question mark `?` in lieu of such union is equivalent. The use of that equivalent alternative syntax SHALL be restricted to [scalar types](#scalar-types) and references to user-defined types, and SHALL NOT be used in [type expressions](#type-expressions). +Using the type `nil` in a union makes a type definition nilable, which means that any instance of that union MAY be a nil data value. When such a union is composed of only one type in addition to `| nil`, use of a trailing question mark `?` instead of the union syntax is equivalent. The use of that equivalent, alternative syntax SHALL be restricted to [scalar types](#scalar-types) and references to user-defined types, and SHALL NOT be used in [type expressions](#type-expressions). In the following example, the type is an object and has two required properties, `name` and `comment`, both defaulting to type `string`. In `example`, `name` is assigned a string value, but comment is nil and this is _not_ allowed because RAML expects a string. @@ -1083,7 +1083,7 @@ types: Declaring the type of a property to be `nil` represents the lack of a value in a type instance. In a RAML context that requires *values* of type `nil` (vs just type declarations), the usual YAML `null` is used, e.g. when the type is `nil | number` you may use `enum: [ 1, 2, ~ ]` or more explicitly/verbosely `enum: [ 1, 2, !!null "" ]`; in non-inline notation you can just omit the value completely, of course. -Nilable values are not the same as optional properties, e.g. to have a `comment` property that is optional and which can also have a `nil` value, you could define it as `comment?: string?` or `comment?: nil | string`. +Nilable values are not the same as optional properties. For example, you can define a `comment` property that is optional and that accepts a `nil` value by using the syntax `comment?: string?` or `comment?: nil | string`. #### Union Type From 8b364c6559e3fa043bb5a257e16e05afdf661da5 Mon Sep 17 00:00:00 2001 From: Jonathan Stoikovitch Date: Wed, 23 Dec 2020 20:16:08 -0800 Subject: [PATCH 37/49] Apply suggestions from code review Co-authored-by: Duke --- versions/raml-10/raml-10.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index 44b98430..dd557583 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -598,7 +598,7 @@ types: Properties of object types are defined using the OPTIONAL **properties** facet. The RAML Specification calls the value of the "properties" facet a "properties declaration". The properties declaration is a map of keys and values. The keys are valid property names for declaring a type instance. The values are either a name of a type or an inline type declaration. -The properties declaration can specify whether a property is required or optional. Alternatively, a trailing question mark (`?`) in the key name MAY be used to indicate that said property is optional. +The properties declaration can specify whether a property is required or optional. Alternatively, a trailing question mark (`?`) in the key name MAY be used to indicate that a property is optional. | Facet | Description | |:----------|:----------| @@ -1247,7 +1247,7 @@ When referencing an inner element of a schema, a RAML processor MUST validate an Facets express various additional restrictions beyond those which types impose on their instances, such as the optional `minimum` and `maximum` facets for numbers, or the `enum` facet for scalars. In addition to the built-in facets, RAML provides a way to declare user-defined facets for any data type. -The user-defined facet is declared using the OPTIONAL `facets` facet in a type declaration. The value of the `facets` facet is a [properties declaration](#property-declarations) object, as is the value of the properties object of a type declaration. Each property in this declaration object is referred to as a **user-defined facet declaration**. Each property name specifies a user-defined facet name. A trailing question mark (`?`) in a property name MAY be used to indicate that said user-defined facet is optional. Each property value specifies the user-defined facet value type as the name of a type or an inline type declaration. +The user-defined facet is declared using the OPTIONAL `facets` facet in a type declaration. The value of the `facets` facet is a [properties declaration](#property-declarations) object, which is also the value of the properties object of a type declaration. Each property in this declaration object is referred to as a **user-defined facet declaration**. Each property name specifies a user-defined facet name. A trailing question mark (`?`) in a property name MAY be used to indicate that a user-defined facet is optional. Each property value specifies the user-defined facet value type as the name of a type or as an inline type declaration. Facet names MUST NOT begin with open parenthesis, to disambiguate the names from annotations. User-defined facet names on a type MUST NOT match built-in facets on that type, nor facet names of any ancestor type in the inheritance chain of the type. @@ -1992,7 +1992,7 @@ types: #### Query Parameters in a Query String -The **queryParameters** node specifies the set of query parameters from which the query string is composed. When applying the restrictions defined by the API, processors MUST regard the query string as a set of query parameters according to the URL encoding format. The value of the queryParameters node is a [properties declaration](#property-declarations) object, as is the value of the properties object of a type declaration. Each property in this declaration object is referred to as a **query parameter declaration**. Each property name specifies an allowed query parameter name. A trailing question mark (`?`) in a property name MAY be used to indicate that said query parameter is optional. Each property value specifies the query parameter value type as the name of a type or an inline type declaration. +The **queryParameters** node specifies the set of query parameters from which the query string is composed. When applying the restrictions defined by the API, processors MUST regard the query string as a set of query parameters according to the URL encoding format. The value of the queryParameters node is a [properties declaration](#property-declarations) object, which is also the value of the properties object of a type declaration. Each property in this declaration object is referred to as a **query parameter declaration**. Each property name specifies an allowed query parameter name. A trailing question mark (`?`) in a property name MAY be used to indicate that a query parameter is optional. Each property value specifies the query parameter value type as the name of a type or an inline type declaration. If a query parameter declaration specifies an array type for the value of the query parameter, processors MUST allow multiple instances of that query parameter in the request or response. In this case, the type of the elements of the array MUST be applied as the type of the value of query parameter instances. From 3c29bde2fe03c8b70a2dac26774b7014970e68a2 Mon Sep 17 00:00:00 2001 From: Jonathan Stoikovitch Date: Wed, 23 Dec 2020 20:17:11 -0800 Subject: [PATCH 38/49] Apply suggestions from code review Co-authored-by: Duke --- 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 b5efa5ad..a00b1a06 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1238,7 +1238,7 @@ Sometimes it is necessary to refer to an element defined in a schema. RAML suppo type: !include elements.xsd#Foo ``` -When referencing an inner element of a JSON or XML schema, a RAML processor MUST validate an instance against that particular element. The RAML specification supports referencing any inner elements in JSON schemas that are valid schemas, any globally defined elements, and complex types in XML schemas. There are only a few restrictions: +When referencing an inner element of a JSON or XML schema, a RAML processor MUST validate an instance against that element. The RAML specification supports referencing any inner elements in JSON schemas that are valid schemas, any globally defined elements, and complex types in XML schemas. There are a few restrictions: * Validation of any XML or JSON instance against inner elements follows the same restrictions as the validation against a regular XML or JSON schema. * Referencing complex types inside an XSD is valid to determine the structure of an XML instance, but since complex types do not define a name for the top-level XML element, these types cannot be used for serializing an XML instance. From d866f210ae7652f38bcfc9ffcd0693a23d947554 Mon Sep 17 00:00:00 2001 From: Jonathan Stoikovitch Date: Wed, 23 Dec 2020 20:18:57 -0800 Subject: [PATCH 39/49] Apply suggestions from code review Co-authored-by: Duke --- 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 88e4318d..1d8c1f48 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -3065,7 +3065,7 @@ A file to be included MAY begin with a RAML fragment identifier line, which cons |:-------------------|:------------| :-----------------------------------| | 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](#defining-types) -| NamedExample | A declaration of the examples facet, whose keys are names of examples and whose values describe each of the examples | [Examples](#defining-examples-in-raml) +| NamedExample | A declaration of the examples facet. The facet's keys are names of examples, and its values describe each of the examples | [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) From bf1cfa3cab82d56972f93455e5fce756fc56ac04 Mon Sep 17 00:00:00 2001 From: Jonathan Stoikovitch Date: Wed, 23 Dec 2020 20:23:14 -0800 Subject: [PATCH 40/49] Apply suggestions from code review Co-authored-by: Duke --- 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 4bc0260d..1ec02f0b 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -2331,7 +2331,7 @@ traits: example: <>=h8duh3uhhu38 # e.g. get=h8duh3uhhu38 ``` -Parameters cannot be used within any file location used in the context of [modularization](https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md#modularization), that is any file location defined in the `!include` tag or as value of any of the `uses` and `extends` nodes. +Parameters cannot be used within any file location that is used in the context of [modularization](https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md#modularization), that is, any file location defined in the `!include` tag or as a value of any of the `uses` or `extends` nodes. ### Declaring HTTP Methods as Optional From 6f6d048807b01a558da726abffd2b32098627a48 Mon Sep 17 00:00:00 2001 From: Jonathan Stoikovitch Date: Wed, 23 Dec 2020 20:48:25 -0800 Subject: [PATCH 41/49] Apply suggestions from code review Co-authored-by: Duke --- versions/raml-10/raml-10.md | 72 ++++++++++++++++++------------------- 1 file changed, 36 insertions(+), 36 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index ee5c6bcf..d8e635a5 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -161,8 +161,8 @@ This document is organized as follows: * **Data types**: a unified, streamlined, and powerful way to model data wherever it appears in an API. * Uniformly covers bodies, URI parameters, headers, and query parameters and eliminates the need for a separate formParameters construct - * Supports wrapping XML and JSON schemas and even referring to sub-schemas, but in many cases just obviates the schemas - * Simplifies coding, compared to JSON Schema or XML Schema (XSD), by virtue of being YAML-based + * Supports wrapping XML and JSON schemas, and referring to sub-schemas, but in many cases, obviates the schemas + * Simplifies coding, compared to JSON Schema or XML Schema (XSD), because it is YAML-based * **Examples**: multiple examples, expressible in YAML, and annotatable, so semantics can be injected * **Annotations**: a tried-and-tested, strongly-typed mechanism for extensibility * **Libraries**: improved modularity for broad reuse of API artifacts @@ -286,7 +286,7 @@ If the baseUri value is a [Template URI](#template-uri), the following reserved |:----------|:----------| | version | The value of the root-level version node -Any other URI template variables appearing in the baseUri MAY be described explicitly within a **baseUriParameters** node at the root of the API definition. The baseUriParameters node has the same semantics and therefor MUST follow the same structure as the [uriParameters](#template-uris-and-uri-parameters) node on a resource node, except that it specifies parameters in the base URI rather than the relative URI of a resource. +Any other URI template variables appearing in the baseUri MAY be described explicitly within a **baseUriParameters** node at the root of the API definition. The baseUriParameters node has the same semantics and therefore MUST follow the same structure as the [uriParameters](#template-uris-and-uri-parameters) node on a resource node, except that it specifies parameters in the base URI rather than the relative URI of a resource. The following example RAML API definition uses a [Template URI](#template-uri) as the base URI. @@ -328,7 +328,7 @@ baseUri: //api.test.com//common// ### Protocols -The OPTIONAL **protocols** node specifies the protocols that an API supports. If the protocols node is not explicitly specified, one or more protocols included in the baseUri node SHALL be used; if the protocols node is explicitly specified, such node specification SHALL override any protocol included in the baseUri node. The protocols node MUST be a non-empty array of strings, of values HTTP and/or HTTPS, and is case-insensitive. +The OPTIONAL **protocols** node specifies the protocols that an API supports. If the protocols node is not explicitly specified, one or more protocols included in the baseUri node SHALL be used; if the protocols node is explicitly specified, such node specification SHALL override any protocol included in the baseUri node. The protocols node MUST be a non-empty array of strings, of values HTTP and/or HTTPS, and be case-insensitive. The following is an example of an API endpoint that accepts both HTTP and HTTPS requests. @@ -553,7 +553,7 @@ The RAML type system defines the following built-in types: * [union](#union-type) via type expression * one of the following [scalar types](#scalar-types): number, boolean, string, date-only, time-only, datetime-only, datetime, file, integer, or nil -Additional to the built-in types, the RAML type system also allows to define [JSON or XML schemas](#using-xml-and-json-schemas). +In addition to the built-in types, the RAML type system also allows for the definition of [JSON or XML schemas](#using-xml-and-json-schemas). The following diagram shows the inheritance tree, starting at the root-level with `any`. @@ -569,7 +569,7 @@ The `any` type has no additional facets. #### Object Type -All types that have the built-in object base type in its inheritance tree MAY use the following facets in their type declarations: +All types that have the built-in object base type in their inheritance tree MAY use the following facets in their type declarations: | Facet | Description | |:----------|:----------| @@ -596,7 +596,7 @@ types: ##### Property Declarations -Properties of object types are defined using the OPTIONAL **properties** facet. The RAML Specification calls the value of the "properties" facet a "properties declaration". The properties declaration MUST be a map of keys and values. The keys are valid property names for declaring a type instance. The values MUST be either a name of a type or an inline type declaration. +Properties of object types are defined using the OPTIONAL **properties** facet. The RAML Specification calls the value of the `properties` facet a "properties declaration". The properties declaration MUST be a map of keys and values. The keys are valid property names for declaring a type instance. The values MUST be either a name of a type or an inline type declaration. The properties declaration MAY specify whether a property is required or optional. @@ -759,9 +759,9 @@ A sub-type MAY override properties of its parent type with the following restric When payloads contain ambiguous types due to unions or inheritance, it is often impossible to discriminate the concrete type of an individual object at runtime. For example, when deserializing the payload into a statically typed language, this problem can occur. -A RAML processor MAY provide an implementation that automatically selects a concrete type from a set of possible types, but a simpler alternative is to store some unique value associated with the type inside the object. +A RAML processor MAY provide an implementation that automatically selects a concrete type from a set of possible types, but a simpler alternative is to store a unique value associated with the type inside the object. -You MAY set the name of an object property using the `discriminator` facet. The name of the object property MAY be used to discriminate the concrete type. The `discriminatorValue` stores the actual value that MAY identify the type of an individual object. By default, the value of `discriminatorValue` is the name of the type. +You MAY set the name of an object property using the `discriminator` facet. The name of the object property MAY be used to discriminate the concrete type. You MAY use the `discriminatorValue` to store the value that identifies the type of an individual object. By default, the value of `discriminatorValue` is the name of the type. Here's an example that illustrates how to use `discriminator`: @@ -795,7 +795,7 @@ data: kind: Employee ``` -You MAY also override the default for `discriminatorValue` for each individual concrete class. The following example replaces the default value of `discriminatorValue` in initial caps with lowercase: +You MAY also override the default for `discriminatorValue` for each individual concrete class. The following example replaces the initial capitalization in the default value of `discriminatorValue` with lowercase characters: ```yaml #%RAML 1.0 @@ -954,7 +954,7 @@ types: ##### Integer -Any JSON number, positive or negative multiple of 1. The integer type inherits its facets from the [number type](#number). +Any JSON number that is a positive or negative multiple of 1. The integer type inherits its facets from the [number type](#number). ```yaml types: @@ -1033,7 +1033,7 @@ types: ##### Nil Type -In RAML, the type `nil` is a scalar type that SHALL allow only nil data values. Specifically, in YAML it allows only YAML's `null` (or its equivalent representations, such as `~`), in JSON it allows only JSON's `null`, and in XML it allows only XML's `xsi:nil`. In headers, URI parameters, and query parameters, the `nil` type SHALL only allow the string value "nil" (case-sensitive); and in turn an instance having the string value "nil" (case-sensitive), when described with the `nil` type, SHALL deserialize to a nil value. +In RAML, the type `nil` is a scalar type that SHALL allow only nil data values. Specifically, in YAML, it allows only YAML's `null` (or its equivalent representations, such as `~`). In JSON, it allows only JSON's `null`, and in XML, it allows only XML's `xsi:nil`. In headers, URI parameters, and query parameters, the `nil` type SHALL only allow the string value "nil" (case-sensitive); and in turn, an instance having the string value "nil" (case-sensitive), when described with the `nil` type, SHALL deserialize to a nil value. In the following example, the type is an object and has two required properties, `name` and `comment`, both defaulting to type `string`. In `example`, `name` is assigned a string value, but comment is nil and this is _not_ allowed because RAML expects a string. @@ -1190,7 +1190,7 @@ types: type: !include person.json ``` -A RAML processor MUST NOT allow types that define an XML or JSON schema to participate in type inheritance or specialization, or effectively in any [type expression](#type-expressions). Therefore, you SHALL NOT define sub-types of these types to declare new properties, add restrictions, set facets, or declare facets. You MAY, however, create simple type wrappers that add annotations, examples, display name, or a description. +A RAML processor MUST NOT allow types that define an XML or JSON schema to participate in type inheritance or specialization, or effectively in any [type expression](#type-expressions). Therefore, you SHALL NOT define sub-types of these types to declare new properties, add restrictions, set facets, or declare facets. You MAY, however, create simple type wrappers that add annotations, examples, a display name, or a description. The following example shows a valid declaration. @@ -1225,13 +1225,13 @@ types: A RAML processor MUST be able to interpret and apply JSON and XML schemas. -A XML schema, or JSON schema, MUST NOT be used where the media type does not allow XML-formatted data, or JSON-formatted data, respectively. XML and JSON schemas are also forbidden in any declaration of query parameters, query string, URI parameters, and headers. +An XML schema, or JSON schema, MUST NOT be used where the media type does not allow XML-formatted data, or JSON-formatted data, respectively. XML and JSON schemas are also forbidden in any declaration of query parameters, query string, URI parameters, and headers. The nodes "schemas" and "types", as well as "schema" and "type", are mutually exclusive and synonymous for compatibility with RAML 0.8. API definitions SHOULD use "types" and "type", as "schemas" and "schema" are deprecated and might be removed in a future RAML version. ##### References to Inner Elements -Sometimes it MAY be necessary to refer to an element defined in a schema. RAML supports that by using URL fragments as shown in the example below. +You MAY refer to an element defined in a schema. RAML supports that by using URL fragments as shown in the example below. ```yaml type: !include elements.xsd#Foo @@ -1240,13 +1240,13 @@ type: !include elements.xsd#Foo When referencing an inner element of a schema, a RAML processor MUST validate an instance against that particular element. The RAML specification supports referencing any inner elements in JSON schemas that are valid schemas, any globally defined elements, and complex types in XML schemas. There are only a few restrictions: * Validation of any XML or JSON instance against inner elements MUST follow the same restrictions as the validation against a regular XML or JSON schema. -* Referencing complex types inside an XML schema is valid to determine the structure of an XML instance, but since complex types do not define a name for the top-level XML element, these types SHALL NOT be used for serializing an XML instance. +* Referencing complex types inside an XML schema is valid for determining the structure of an XML instance. However, because complex types do not define a name for the top-level XML element, these types SHALL NOT be used for serializing an XML instance. ### User-defined Facets Facets express various additional restrictions beyond those which types impose on their instances, such as the optional `minimum` and `maximum` facets for numbers, or the `enum` facet for scalars. In addition to the built-in facets, RAML provides a way to declare user-defined facets for any data type. -The user-defined facet is declared using the OPTIONAL `facets` facet in a type declaration. The value of the `facets` facet MUST be a map. The key names the user-defined facet. The corresponding value defines the concrete value that the respective facet can take. The syntax of a [property declaration](#property-declarations) and user-defined facet declaration are the same. A facet restricts instances of a subtype, not its type, based on the concrete value defined in the facet declaration. +The user-defined facet is declared using the OPTIONAL `facets` facet in a type declaration. The value of the `facets` facet MUST be a map. The key names the user-defined facet. The corresponding value defines the concrete value that the respective facet can take. The syntax of a [property declaration](#property-declarations) and a user-defined facet declaration are the same. A facet restricts instances of a sub-type, not its type, based on the concrete value defined in the facet declaration. Facet names MUST NOT begin with open parenthesis, to disambiguate the names from annotations. User-defined facet names on a type MUST NOT match built-in facets on that type, nor facet names of any ancestor type in the inheritance chain of the type. @@ -1270,7 +1270,7 @@ types: In this example, declaring the `noHolidays` facet and defining its values to be boolean makes it possible to restrict date instances that fall on holidays. Instances of any inheriting type, such as the `PossibleMeetingDate` type, must have values that do not fall on holidays. -User-defined facets by definition are not built into this RAML specification, and hence their semantic MAY not be understood by all RAML processors. Consequently, a RAML processor may or may not choose to use user-defined facets on a type in validating instances of that type. In the example above, a RAML processor may or may not assign a meaning to `noHolidays`, and therefore, may choose to ignore the `noHolidays: true` value in validating instances of `PossibleMeetingDate`. +By definition, user-defined facets are not built into this RAML specification, and therefore, their semantics might not be understood by all RAML processors. Consequently, a RAML processor MAY (or may not) choose to use user-defined facets on a type in validating instances of that type. In the example above, a RAML processor may or may not assign a meaning to `noHolidays`, and therefore, may choose to ignore the `noHolidays: true` value in validating instances of `PossibleMeetingDate`. ### Determine Default Types @@ -1330,7 +1330,7 @@ types: ### Type Expressions -Type expressions provide a powerful way of referring to, and even defining, types. Type expressions MAY be used wherever a type is expected. The simplest type expression is just the name of a type. Using type expressions, you MAY devise type unions, arrays, maps, and other things. +Type expressions provide a powerful way of referring to, and even defining, types. Type expressions MAY be used wherever a type is expected. The simplest type expression is the name of a type. Using type expressions, you MAY devise type unions, arrays, maps, and other things. |Expression | Description | |:--------|:------------| @@ -1504,7 +1504,7 @@ record: # {key} - unique id #### Single Example -The OPTIONAL **example** facet MAY be used to attach an example of a type instance to the type declaration. There are two ways to represent the example facet value: as an explicit description of a specific type instance and as a map that contains additional facets. +The OPTIONAL **example** facet MAY be used to attach an example of a type instance to the type declaration. There are two ways to represent the example facet value: as an explicit description of a specific type instance, or as a map that contains additional facets. ##### As an explicit description of a specific type instance @@ -1522,10 +1522,10 @@ The map MAY contain the following additional facets: | Facet | Description | |:--------|:------------| | displayName? | An alternate, human-friendly name for the example. If the example is part of an examples node, the default value is the unique identifier that is defined for this example. -| description? | A substantial, human-friendly description for an example. Its value MUST be a string and MAY be formatted using [markdown](#markdown). -| (<annotationName>)? | [Annotations](#annotations) to be applied to this API. An annotation MUST be 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. +| description? | A substantial, human-friendly description for an example. Its value MUST be a string and MAY be formatted using [Markdown](#markdown). +| (<annotationName>)? | [Annotations](#annotations) to be applied to this API. An annotation MUST be 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. | value | The actual example of a type instance. -| strict? | Validates the example against any type declaration (the default), or not. Set this to false to avoid validation. +| strict? | Validates the example against any type declaration (the default), or not. Set this facet to false to avoid validation. For example: @@ -1741,19 +1741,19 @@ The URIs in the following example would ALWAYS be ALLOWED. ### Resource Property -The value of a resource node MUST be a map whose key-value pairs are described in the following table. +The value of a resource node MUST be a map containing the key-value pairs described in the following table. | Name | Description | |:--------|:------------| | displayName? | An alternate, human-friendly name for the resource. If the displayName node is not defined for a resource, documentation tools SHOULD refer to the resource by its key, which acts as the resource name. For example, tools SHOULD refer to the relative URI `/jobs`. -| description? | A substantial, human-friendly description of a resource. Its value MUST be a string and MAY be formatted using [markdown](#markdown). -| (<annotationName>)? | [Annotations](#annotations) to be applied to this API. An annotation MUST be 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. +| description? | A substantial, human-friendly description of a resource. Its value MUST be a string and MAY be formatted using [Markdown](#markdown). +| (<annotationName>)? | [Annotations](#annotations) to be applied to this API. An annotation MUST be 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. | get?
patch?
put?
post?
delete?
options?
head? | The object describing the [method](#methods). | is? | A list of [traits to apply](#applying-resource-types-and-traits) to all methods declared (implicitly or explicitly) for this resource. Individual methods can override this declaration. | type? | The [resource type](#applying-resource-types-and-traits) that this resource inherits. | securedBy? | The [security schemes](#applying-security-schemes) that apply to all methods declared (implicitly or explicitly) for this resource. | uriParameters? | Detailed information about any URI parameters of this resource. -| /<relativeUri>? | A nested resource, which is identified as any node whose name begins with a slash (`/`), and SHALL therefore be treated as a relative URI. +| /<relativeUri>? | A nested resource is any node whose name begins with a slash (`/`). This resource SHALL therefore be treated as a relative URI. ### Template URIs and URI Parameters @@ -1833,7 +1833,7 @@ version: v1 description: An item in the collection of all files ``` -Although a URI parameter MAY be explicitly specified as optional, it SHOULD be required when surrounded directly by slashes (`/`). In this case, the URI parameter constitutes a complete URI path fragment, for example `.../{objectId}/...`. It usually makes no sense to allow a URI to contain adjacent slashes, enclosing no characters, for example `...//...`. Hence, a URI parameter SHOULD be specified as optional only when it appears adjacent to other text. For example, `/people/~{fieldSelectors}` indicates that URI parameter `{fieldSelectors}` can be blank, and therefore optional, implying that `/people/~` is a valid relative URI. +Although a URI parameter MAY be explicitly specified as optional, it SHOULD be required when surrounded directly by slashes (`/`). In this case, the URI parameter constitutes a complete URI path fragment, for example `.../{objectId}/...`. It usually makes no sense to allow a URI to contain adjacent slashes, enclosing no characters, for example, `...//...`. Therefore, a URI parameter SHOULD be specified as optional only when it appears adjacent to other text. For example, `/people/~{fieldSelectors}` indicates that URI parameter `{fieldSelectors}` can be blank, and therefore optional, which implies that `/people/~` is a valid relative URI. A special URI reserved parameter, **ext**, MAY be specified explicitly in a uriParameters node. Its meaning is reserved for use by a client to specify that the body of the request or response be of the associated media type. @@ -1856,7 +1856,7 @@ version: v1 ## Methods -RESTful API methods are operations that are performed on a resource. The OPTIONAL properties **get**, **patch**, **put**, **post**, **delete**, **head**, and **options** of a resource define its methods; these correspond to the HTTP methods defined in the HTTP version 1.1 specification [RFC2616](https://www.ietf.org/rfc/rfc2616.txt) and its extension, [RFC5789](https://tools.ietf.org/html/rfc5789). The value of these method properties MUST be a map with the following key-value pairs: +RESTful API methods are operations that are performed on a resource. The OPTIONAL properties **get**, **patch**, **put**, **post**, **delete**, **head**, and **options** of a resource define its methods. These properties correspond to the HTTP methods defined in the HTTP version 1.1 specification [RFC2616](https://www.ietf.org/rfc/rfc2616.txt) and its extension, [RFC5789](https://tools.ietf.org/html/rfc5789). The value of these method properties MUST be a map with the following key-value pairs: | Name | Description | |:--------|:------------| @@ -1944,7 +1944,7 @@ An API method MAY support or require a query string in the URL on which the meth #### The Query String as a Whole -The **queryString** node MAY be used to specify the query string as a whole, rather than as name-value pairs. The queryString value MUST either be the name of a data type or an inline data type declaration, including a data type expression. In either case, all base types in type hierarchy of the data type MUST be either a scalar type or the object type, after fully expanding any union type expressions at every level of the type hierarchy. +The **queryString** node MAY be used to specify the query string as a whole, rather than as name-value pairs. The queryString value MUST be either the name of a data type or an inline data type declaration, including a data type expression. In either case, all base types in type hierarchy of the data type MUST be either a scalar type or the object type, after fully expanding any union type expressions at every level of the type hierarchy. If the type is derived from a scalar type, the query string as a whole MUST be described by the type. @@ -2070,12 +2070,12 @@ Keys SHOULD BE numeric, for example 200 or 204. Processors MUST treat these nume ### Response Declaration -The value of a response declaration MUST be a map with the following key-value pairs +The value of a response declaration MUST be a map with the following key-value pairs: | Name | Description | |:--------|:------------| -| description? | A substantial, human-friendly description of a response. Its value MUST ve a string and MAY be formatted using [markdown](#markdown). -| (<annotationName>) | [Annotations](#annotations) to be applied to this API. An annotation MUST be 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. +| description? | A substantial, human-friendly description of a response. Its value MUST be a string and MAY be formatted using [Markdown](#markdown). +| (<annotationName>) | [Annotations](#annotations) to be applied to this API. An annotation MUST be 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. | headers? | Detailed information about any response headers returned by this method | body? | The body of the response @@ -2131,7 +2131,7 @@ Moreover, resource and method declarations are frequently repetitive. For exampl A resource type, like a resource, can specify security schemes, methods, and other nodes. A resource that uses a resource type inherits its nodes. A resource type can also use, and thus inherit from, another resource type. Resource types and resources are related through an inheritance chain pattern. A resource type definition MUST NOT incorporate nested resources. A resource type definition cannot be used to generate nested resources when the definition is applied to a resource. A resource type definition does not apply to its own existing nested resources. -A trait, like a method, can provide method-level nodes such as description, headers, query string parameters, and responses. Methods that use one or more traits inherit nodes of those traits. A resource and resource type can also use, and thus inherit from, one or more traits, which then apply to all methods of the resource and resource type. Traits are related to methods through a mixin pattern. +A trait, like a method, can provide method-level nodes such as a description, headers, query string parameters, and responses. Methods that use one or more traits inherit nodes of those traits. A resource and resource type can also use, and thus inherit from, one or more traits, which then apply to all methods of the resource and resource type. Traits are related to methods through a mixin pattern. ### Declaring Resource Types and Traits @@ -3034,7 +3034,7 @@ RAML provides several mechanisms to help modularize the ecosystem of an API spec ### 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. Therefor, the !include tag cannot be used in any type expression or multiple inheritance. +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. Therefore, the !include tag cannot be used in any type expression or multiple inheritance. 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. @@ -3210,7 +3210,7 @@ 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). +| 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. From 9010ccb7c0724e11081cbfb11bd2e441c119ea53 Mon Sep 17 00:00:00 2001 From: Jonathan Stoikovitch Date: Mon, 28 Dec 2020 15:45:54 -0800 Subject: [PATCH 42/49] Apply suggestions from code review Co-authored-by: Duke Co-authored-by: priyaayyar <50642006+priyaayyar@users.noreply.github.com> --- versions/raml-10/raml-10.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index dc588205..24169dc7 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -3074,13 +3074,13 @@ A file to be included MAY begin with a RAML fragment identifier line, which cons | Extension | An extension file | [Extensions](#extensions) | SecurityScheme | A definition of a security scheme | [Security Schemes](#security-schemes) -In addition to any nodes allowed in any of the "Relevant RAML Specification Sections" above, the following OPTIONAL node is allowed: +In addition to the nodes allowed in any of the Relevant RAML Specification Sections above, the following OPTIONAL node is allowed: |Allowed Node | Description | |:------------|:------------| | uses? | Imported external [libraries](#libraries) for use within the RAML typed fragment. | -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 and any `uses` node 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. +If a file begins with a RAML fragment identifier line, and the fragment identifier is not a Library, Overlay, or Extension, the contents of the file after the removal of the RAML fragment identifier line and any `uses` node 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 typed fragment file. @@ -3216,7 +3216,7 @@ In addition to any nodes allowed at the root of [RAML typed fragments](#typed-fr |Name | Description | |:--------|:------------| -| types?
schemas?
resourceTypes?
traits?
securitySchemes?
annotationTypes?
(<annotationName>)? | 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. +| types?
schemas?
resourceTypes?
traits?
securitySchemes?
annotationTypes?
(<annotationName>)? | The definition of each node is the same as that of the corresponding node at the root of a RAML document. A library supports the 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. @@ -3245,7 +3245,7 @@ resourceTypes: #### Applying Libraries -Any number of libraries can be applied by using the OPTIONAL **uses** node at the root of a RAML or RAML typed 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. +You can apply any number of libraries by using the OPTIONAL **uses** node at the root of a RAML or RAML typed 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 a document that applies a library, the data types, resource types, traits, security schemes, and annotation types in the library become available within the document. The assets in the library are referenced within the document 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. The library name defines a namespace for the library nodes within the context in which 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. From cc3cd84a8ad8bbc9f5f50f4c53c97a9a1add863c Mon Sep 17 00:00:00 2001 From: Jonathan Stoikovitch Date: Mon, 28 Dec 2020 15:55:46 -0800 Subject: [PATCH 43/49] Apply suggestions from code review Co-authored-by: Duke --- versions/raml-10/raml-10.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index df4ab38f..5b7fa178 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1170,9 +1170,8 @@ types: HomeAnimal: [ HasHome | IsOnFarm , Dog | Cat | Parrot ] ``` -A union type MAY use facets defined by any of its member types as long as all member types in the union accept those facets. +A union type MAY use facets defined by any of its member types as long as all member types in the union accept those facets, for example: -For example: ```yaml types: From ab342e179917117db934b3a2930920058b325da0 Mon Sep 17 00:00:00 2001 From: Jonathan Stoikovitch Date: Mon, 28 Dec 2020 16:44:37 -0800 Subject: [PATCH 44/49] Apply suggestions from code review Co-authored-by: Duke --- 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 7f933cbd..128b56ea 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -3314,7 +3314,7 @@ API definitions might need to be extended in a variety of ways for different nee 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. The resolution of paths in an overlay or extension document, such as those for `!include` tags or libraries, MUST be relative to the document from which the reference is being made, as opposed to the API root 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. The resolution of paths in an overlay or extension document, such as those for `!include` tags or libraries, MUST be relative to the document from which the reference is made, as opposed to the API root document. 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. From 968b98f1513735ced8926fee043732e42952f3ce Mon Sep 17 00:00:00 2001 From: Jonathan Stoikovitch Date: Mon, 28 Dec 2020 16:50:37 -0800 Subject: [PATCH 45/49] Apply suggestions from code review Co-authored-by: priyaayyar <50642006+priyaayyar@users.noreply.github.com> --- 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 ec65afcd..0ac84bd4 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1526,7 +1526,7 @@ The map can contain the following additional facets: | description? | A substantial, human-friendly description for an example. Its value is a string and 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. | value | The actual example of a type instance. -| strict? | Validates the example against any type declaration (the default). Set this to false to prevent validation. +| strict? | Validates the example against any type declaration (default). Set this to false to prevent validation. For example: From bab915bb658aab285c868d83c471c5f6d41af45d Mon Sep 17 00:00:00 2001 From: Jonathan Stoikovitch Date: Mon, 28 Dec 2020 17:05:07 -0800 Subject: [PATCH 46/49] Apply suggestions from code review Co-authored-by: Duke --- 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 61012a3d..0c2e1c2d 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -2200,7 +2200,7 @@ resourceTypes: A resource can specify the resource type from which it is derived using the OPTIONAL **type** node. The value MUST be the name of a resource type defined within the root-level resourceTypes node or in a library. Resource type definitions do not apply to existing nested resources. -Similarly, a method can specify one or more traits it inherits using the OPTIONAL **is** node. The value of a trait MUST be an array of any number of elements where each MUST be the name of a trait defined within the root-level traits node or in a library. A trait can also be applied to a resource by using the **is** node. Using this node is equivalent to applying the trait to all methods for that resource, whether declared explicitly in the resource definition or inherited from a resource type. A trait is applied to a method in left-to-right order, according to the traits defined in the **is** node. Trait definitions do not apply to nested resources. +Similarly, a method can specify one or more traits it inherits by using the OPTIONAL **is** node. The value of a trait MUST be an array of any number of elements. Each element MUST be the name of a trait defined within the root-level traits node or in a library. A trait can also be applied to a resource by using the **is** node. Using this node is equivalent to applying the trait to all methods for that resource, whether the method is declared explicitly in the resource definition or inherited from a resource type. A trait is applied to a method in left-to-right order, according to the traits defined in the **is** node. Trait definitions do not apply to nested resources. The following example illustrates the application of resource types and traits. From 4f98b23c8a819ef87d254572df4ffd793d69c758 Mon Sep 17 00:00:00 2001 From: Jonathan Stoikovitch Date: Mon, 28 Dec 2020 17:23:10 -0800 Subject: [PATCH 47/49] Apply suggestions from code review Co-authored-by: Duke --- versions/raml-10/raml-10.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/raml-10/raml-10.md b/versions/raml-10/raml-10.md index d8e635a5..f6b4273d 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1874,7 +1874,7 @@ RESTful API methods are operations that are performed on a resource. The OPTIONA ### Headers -An API's methods MAY support or require various HTTP headers. The OPTIONAL **headers** node MAY be used to explicitly specify those headers. The value of the headers node MUST be a map, specifically a [properties declaration](#property-declarations), as is the value of the properties object of a type declaration. Each property in this declaration object is a header **declaration**. Each property name specifies an allowed header name. Each property value specifies the header value type as a type name or an inline type declaration. +An API's methods MAY support or require various HTTP headers. The OPTIONAL **headers** node MAY be used to explicitly specify those headers. Like the value of the properties node, the value of the headers node MUST be a map, specifically a [properties declaration](#property-declarations). Each property in this declaration object is a header **declaration**. Each property name specifies an allowed header name. Each property value specifies the header value type as a type name or an inline type declaration. The following simple example shows a post method with a single HTTP header named Zencoder-Api-Key of (implied) string type. @@ -1940,7 +1940,7 @@ traits: ### Query Strings and Query Parameters -An API method MAY support or require a query string in the URL on which the method is invoked. The query string in a URL MUST follow [RFC3986](https://www.ietf.org/rfc/rfc3986.txt) as the part of the URL following the question mark separator (`?`) and preceding any fragment (`#`) separator. The query string MAY be specified either by the OPTIONAL **queryString** node or by the OPTIONAL **queryParameters** node. The queryString and queryParameters nodes SHALL BE mutually exclusive: processors MUST NOT allow both to be specified, explicitly or implicitly, on the same method of the same resource. +An API method MAY support or require a query string in the URL on which the method is invoked. The query string in a URL MUST follow the [RFC3986](https://www.ietf.org/rfc/rfc3986.txt) specification for the part of the URL following the question mark separator (`?`) and preceding any fragment (`#`) separator. The query string MAY be specified either by the OPTIONAL **queryString** node or by the OPTIONAL **queryParameters** node. The queryString and queryParameters nodes SHALL BE mutually exclusive: processors MUST NOT allow both to be specified, explicitly or implicitly, on the same method of the same resource. #### The Query String as a Whole From eef5cc90ce179e5707f0c50f61de9dc1214afc84 Mon Sep 17 00:00:00 2001 From: Jonathan Stoikovitch Date: Tue, 29 Dec 2020 12:00:10 -0800 Subject: [PATCH 48/49] Apply suggestions from code review Co-authored-by: Duke --- 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 f6b4273d..576eaa54 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1456,7 +1456,7 @@ types: Section [union types](#union-multiple-inheritance) illustrates another example of how to validate types that use multiple inheritance and union types. -If a sub-type inherits properties having the same name from at least two of its parent types, the sub-type SHALL keep all restrictions applied to those properties with two exceptions: 1) a "pattern" facet when a parent type already declares a "pattern" facet 2) a user-defined facet when another user-defined facet has the same value. In these cases, an invalid type declaration occurs. +If a sub-type inherits properties having the same name from at least two of its parent types, the sub-type SHALL keep all restrictions applied to those properties with two exceptions: 1) a `pattern` facet when a parent type already declares a `pattern` facet 2) a user-defined facet when another user-defined facet has the same value. In these cases, an invalid type declaration occurs. ### Inline Type Declarations From 2e28449021497f5f0f14c524c9406de90a49e60f Mon Sep 17 00:00:00 2001 From: Jonathan Stoikovitch Date: Fri, 8 Jan 2021 16:46:41 -0800 Subject: [PATCH 49/49] Apply suggestions from code review Co-authored-by: Duke --- 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 0ac84bd4..df599836 100644 --- a/versions/raml-10/raml-10.md +++ b/versions/raml-10/raml-10.md @@ -1484,7 +1484,7 @@ title: My API With Types ### Defining Examples in RAML -It is highly RECOMMENDED that API documentation include a rich selection of examples. RAML supports either the definition of multiple examples or a single one for any given instance of a type declaration. In addition to YAML by default, processors SHOULD support JSON and XML representations of examples. Processors MAY support additional formats. Note that type definition is agnostic to example encoding such that, e.g. examples in YAML will work for JSON or XML, and in reverse for any chosen combination of those three supported encodings. +It is highly RECOMMENDED that API documentation include a rich selection of examples. RAML supports either the definition of multiple examples or a single one for any given instance of a type declaration. In addition to supporting YAML by default, processors SHOULD support JSON and XML representations of examples. Processors MAY support additional formats. Note that type definition is agnostic to example encoding, so examples in YAML will work for JSON or XML, and vice versa, for any chosen combination of those three supported encodings. #### Multiple Examples