diff --git a/versions/4.0.0.md b/versions/4.0.0.md
index 7c4d640c0e..084f34a728 100644
--- a/versions/4.0.0.md
+++ b/versions/4.0.0.md
@@ -51,6 +51,8 @@ An OpenAPI definition can then be used by documentation generation tools to disp
- [Header Object](#headerObject)
- [Tag Object](#tagObject)
- [Reference Object](#referenceObject)
+ - [Merge Object](#mergeObject)
+ - [Merge Object Spec](#mergeObjectSpec)
- [Schema Object](#schemaObject)
- [Discriminator Object](#discriminatorObject)
- [XML Object](#xmlObject)
@@ -174,7 +176,7 @@ Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown
Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-4.2).
Relative references are resolved using the URLs defined in the [`Server Object`](#serverObject) as a Base URI.
-Relative references used in `$ref` are processed as per [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03), using the URL of the current document as the base URI. See also the [Reference Object](#referenceObject).
+Relative references used in `$ref` an are processed as per [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03), using the URL of the current document as the base URI. See also the [Reference Object](#referenceObject).
### Schema
@@ -443,11 +445,11 @@ All objects defined within the components object will have no effect on the API
Field Name | Type | Description
---|:---|---
- schemas | Map[`string`, [Schema Object](#schemaObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Schema Objects](#schemaObject).
+ schemas | Map[`string`, [Schema Object](#schemaObject) \| [Reference Object](#referenceObject)] \| [Merge Object](#mergeObject) | An object to hold reusable [Schema Objects](#schemaObject).
responses | Map[`string`, [Response Object](#responseObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Response Objects](#responseObject).
parameters | Map[`string`, [Parameter Object](#parameterObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Parameter Objects](#parameterObject).
examples | Map[`string`, [Example Object](#exampleObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Example Objects](#exampleObject).
- requestBodies | Map[`string`, [Request Body Object](#requestBodyObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Request Body Objects](#requestBodyObject).
+ requestBodies | Map[`string`, [Request Body Object](#requestBodyObject) \| [Reference Object](#referenceObject)] \| [Merge Object](#mergeObject) | An object to hold reusable [Request Body Objects](#requestBodyObject).
headers | Map[`string`, [Header Object](#headerObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Header Objects](#headerObject).
securitySchemes| Map[`string`, [Security Scheme Object](#securitySchemeObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Security Scheme Objects](#securitySchemeObject).
links | Map[`string`, [Link Object](#linkObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Link Objects](#linkObject).
@@ -1003,7 +1005,7 @@ Field Name | Type | Description
style | `string` | Describes how the parameter value will be serialized depending on the type of the parameter value. Default values (based on value of `in`): for `query` - `form`; for `path` - `simple`; for `header` - `simple`; for `cookie` - `form`.
explode | `boolean` | When this is true, parameter values of type `array` or `object` generate separate parameters for each value of the array or key-value pair of the map. For other types of parameters this property has no effect. When [`style`](#parameterStyle) is `form`, the default value is `true`. For all other styles, the default value is `false`.
allowReserved | `boolean` | Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-2.2) `:/?#[]@!$&'()*+,;=` to be included without percent-encoding. This property only applies to parameters with an `in` value of `query`. The default value is `false`.
-schema | [Schema Object](#schemaObject) \| [Reference Object](#referenceObject) | The schema defining the type used for the parameter.
+schema | [Schema Object](#schemaObject) \| [Reference Object](#referenceObject) \| [Merge Object](#mergeObject) | The schema defining the type used for the parameter.
example | Any | Example of the media type. The example SHOULD match the specified schema and encoding properties if present. The `example` field is mutually exclusive of the `examples` field. Furthermore, if referencing a `schema` which contains an example, the `example` value SHALL _override_ the example provided by the schema. To represent examples of media types that cannot naturally be represented in JSON or YAML, a string value can contain the example with escaping where necessary.
examples | Map[ `string`, [Example Object](#exampleObject) \| [Reference Object](#referenceObject)] | Examples of the media type. Each example SHOULD contain a value in the correct format as specified in the parameter encoding. The `examples` field is mutually exclusive of the `example` field. Furthermore, if referencing a `schema` which contains an example, the `examples` value SHALL _override_ the example provided by the schema.
@@ -1342,7 +1344,7 @@ Each Media Type Object provides schema and examples for the media type identifie
##### Fixed Fields
Field Name | Type | Description
---|:---:|---
-schema | [Schema Object](#schemaObject) \| [Reference Object](#referenceObject) | The schema defining the type used for the request body.
+schema | [Schema Object](#schemaObject) \| [Reference Object](#referenceObject) \| [Merge Object](#mergeObject) | The schema defining the type used for the request body.
example | Any | Example of the media type. The example object SHOULD be in the correct format as specified by the media type. The `example` field is mutually exclusive of the `examples` field. Furthermore, if referencing a `schema` which contains an example, the `example` value SHALL _override_ the example provided by the schema.
examples | Map[ `string`, [Example Object](#exampleObject) \| [Reference Object](#referenceObject)] | Examples of the media type. Each example object SHOULD match the media type and specified schema if present. The `examples` field is mutually exclusive of the `example` field. Furthermore, if referencing a `schema` which contains an example, the `examples` value SHALL _override_ the example provided by the schema.
encoding | Map[`string`, [Encoding Object](#encodingObject)] | A map between a property name and its encoding information. The key, being the property name, MUST exist in the schema as a property. The encoding object SHALL only apply to `requestBody` objects when the media type is `multipart` or `application/x-www-form-urlencoded`.
@@ -1621,12 +1623,12 @@ SHOULD be the response for a successful operation call.
##### Fixed Fields
Field Name | Type | Description
---|:---:|---
-default | [Response Object](#responseObject) \| [Reference Object](#referenceObject) | The documentation of responses other than the ones declared for specific HTTP response codes. Use this field to cover undeclared responses. A [Reference Object](#referenceObject) can link to a response that the [OpenAPI Object's components/responses](#componentsResponses) section defines.
+default | [Response Object](#responseObject) \| [Reference Object](#referenceObject) \| [Merge Object](#mergeObject) | The documentation of responses other than the ones declared for specific HTTP response codes. Use this field to cover undeclared responses. A [Reference Object](#referenceObject) can link to a response that the [OpenAPI Object's components/responses](#componentsResponses) section defines.
##### Patterned Fields
Field Pattern | Type | Description
---|:---:|---
-[HTTP Status Code](#httpCodes) | [Response Object](#responseObject) \| [Reference Object](#referenceObject) | Any [HTTP status code](#httpCodes) can be used as the property name, but only one property per code, to describe the expected response for that HTTP status code. A [Reference Object](#referenceObject) can link to a response that is defined in the [OpenAPI Object's components/responses](#componentsResponses) section. This field MUST be enclosed in quotation marks (for example, "200") for compatibility between JSON and YAML. To define a range of response codes, this field MAY contain the uppercase wildcard character `X`. For example, `2XX` represents all response codes between `[200-299]`. The following range definitions are allowed: `1XX`, `2XX`, `3XX`, `4XX`, and `5XX`. If a response range is defined using an explicit code, the explicit code definition takes precedence over the range definition for that code.
+[HTTP Status Code](#httoppCodes) | [Response Object](#responseObject) \| [Reference Object](#referenceObject) | Any [HTTP status code](#httpCodes) can be used as the property name, but only one property per code, to describe the expected response for that HTTP status code. A [Reference Object](#referenceObject) can link to a response that is defined in the [OpenAPI Object's components/responses](#componentsResponses) section. This field MUST be enclosed in quotation marks (for example, "200") for compatibility between JSON and YAML. To define a range of response codes, this field MAY contain the uppercase wildcard character `X`. For example, `2XX` represents all response codes between `[200-299]`. The following range definitions are allowed: `1XX`, `2XX`, `3XX`, `4XX`, and `5XX`. If a response range is defined using an explicit code, the explicit code definition takes precedence over the range definition for that code.
This object MAY be extended with [Specification Extensions](#specificationExtensions).
@@ -1682,7 +1684,7 @@ Describes a single response from an API Operation, including design-time, static
##### Fixed Fields
Field Name | Type | Description
---|:---:|---
-description | `string` | **REQUIRED**. A short description of the response. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation.
+description | `string` | A short description of the response. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation.
headers | Map[`string`, [Header Object](#headerObject) \| [Reference Object](#referenceObject)] | Maps a header name to its definition. [RFC7230](https://tools.ietf.org/html/rfc7230#page-22) states header names are case insensitive. If a response header is defined with the name `"Content-Type"`, it SHALL be ignored.
content | Map[`string`, [Media Type Object](#mediaTypeObject)] | A map containing descriptions of potential response payloads. The key is a media type or [media type range](https://tools.ietf.org/html/rfc7231#appendix-D) and the value describes it. For responses that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
links | Map[`string`, [Link Object](#linkObject) \| [Reference Object](#referenceObject)] | A map of operations links that can be followed from the response. The key of the map is a short name for the link, following the naming constraints of the names for [Component Objects](#componentsObject).
@@ -2233,6 +2235,123 @@ $ref: Pet.yaml
$ref: definitions.yaml#/Pet
```
+#### Merge Object
+
+A simple object containing the specification to allow merging multiple components in the specification, internally and externally into a single output object combining fields from all of them.
+
+The Merge Object is defined by [JSON Patch](https://tools.ietf.org/html/rfc6902) and follows the same structure, behavior and rules.
+
+Notice that merge objects can only be added in the allowed locations in this specification.
+
+##### Fixed Fields
+Field Name | Type | Description
+---|:---:|---
+$merge | [Merge Object Spec](#mergeObjectSpec) | **REQUIRED**. The specification of the merge operation.
+
+This object cannot be extended with additional properties and any properties added SHALL be ignored.
+
+
+#### Merge Object Spec
+
+Details of the merge operation to be applied to a set components in the specification.
+
+The Merge Object Spec is defined by [JSON Patch](https://tools.ietf.org/html/rfc6902) and follows the same structure, behavior and rules.
+
+##### Fixed Fields
+Field Name | Type | Description
+---|:---:|---
+source | [Request Body Object](#requestBodyObject) \| [Response Object](#responseObject) \| [Schema Object](#schemaObject) \| [Reference Object](#referenceObject) \| [Merge Object](#mergeObject) | **REQUIRED**. The base object used in the merge transformation
+with | \[ [Request Body Object](#requestBodyObject) \| [Response Object](#responseObject) \| [Schema Object](#schemaObject) \| [Reference Object](#referenceObject) \] | **REQUIRED**. The list of objects to be merged on top of the base object
+
+This object cannot be extended with additional properties and any properties added SHALL be ignored.
+
+
+##### Merge Object Spec Example
+
+```json
+{
+ "$merge": {
+ "source": {
+ "description": "returns an Account",
+ "content": {
+ "application/json": {
+ "schema": { "$ref": "#/components/schemas/Account" }
+ }
+ }
+ },
+ "with": [
+ {
+ "headers": {
+ "X-Rate-Limit-Limit": {
+ "description": "The number of allowed requests in the current period",
+ "schema": {
+ "type": "integer"
+ }
+ },
+ "X-Rate-Limit-Remaining": {
+ "description": "The number of remaining requests in the current period",
+ "schema": {
+ "type": "integer"
+ }
+ },
+ "X-Rate-Limit-Reset": {
+ "description": "The number of seconds left in the current period",
+ "schema": {
+ "type": "integer"
+ }
+ }
+ }
+ }
+ ]
+ }
+}
+```
+
+```yaml
+$merge:
+ source:
+ description: returns an Account
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/Account
+ with:
+ - headers:
+ X-Rate-Limit-limit:
+ description: The number of allowed requests in the current period
+ schema:
+ type: integer
+ X-Rate-Limit-Remaining:
+ description: The number of remaining requests in the current period
+ schema:
+ type: integer
+ X-Rate-Limit-Reset:
+ description: The number of seconds left in the current period
+ schema:
+ type: integer
+```
+
+##### Relative and absolute references Merge Object Spec example
+```json
+{
+ "$merge": {
+ "source": { "$ref": "#/components/responses/Accounts" },
+ "with": [
+ { "$ref": "library.json#/components/responses/rate-limit" }
+ ]
+ }
+}
+```
+
+```yaml
+$merge:
+ source:
+ $ref: "#/components/responses/Accounts"
+ with:
+ - $ref: "library.json#/components/responses/rate-limit"
+```
+
+
#### Schema Object
The Schema Object allows the definition of input and output data types.