introducing merge directive

versions/4.0.0.md

@@ -50,7 +50,7 @@ An OpenAPI definition can then be used by documentation generation tools to disp
 		- [Link Object](#linkObject)
 		- [Header Object](#headerObject)
 		- [Tag Object](#tagObject)
-		- [Reference Object](#referenceObject)
+		- [Reference Object](#referenceObject)		
 		- [Schema Object](#schemaObject)
 		- [Discriminator Object](#discriminatorObject)
 		- [XML Object](#xmlObject)
@@ -60,6 +60,7 @@ An OpenAPI definition can then be used by documentation generation tools to disp
 		- [Security Requirement Object](#securityRequirementObject)
 	- [Specification Extensions](#specificationExtensions)
 	- [Security Filtering](#securityFiltering)
+	- [Merge directive](#merge-directives)
 - [Appendix A: Revision History](#revisionHistory)
 
 
@@ -2233,6 +2234,83 @@ $ref: Pet.yaml
 $ref: definitions.yaml#/Pet
 ```
 
+### Reference object shortcuts
+
+Referencing reusable components with reference object is often annoying
+and requires a lot of typing. This specification provides a following shortcut rules 
+which allow to reduce amount of bloat and reduce verbosity of OAS specifications.
+
+1. Instead of using full form of reference object you may use a string literal containing the location of the JSON value being referenced. So instead of 
+
+```yaml
+application/json:
+            schema:
+              type: array
+              items:
+                $ref: '#/components/schemas/pet'
+```
+
+you may just write:
+
+```yaml
+application/json:
+       schema:
+           type: array
+           items: '#/components/schemas/pet'
+```
+2. In the cases when you are referencing a component defined locally it is allowed to use local key of the component, so it is allowed to rewrite previous example in even shorter way:
+
+```yaml
+application/json:
+      schema:
+         type: array
+         items: pet
+```
+
+#### Resolution rules:
+
+when using reference object short cut, following resolution rules should be applied.
+
+Test if the string points to locally defined component of appropriate kind, this depends from the context of parsing and is defined by the following list:
+
+Schema Object - schemas
+Response Object - responses
+Parameter Object -parameters
+Example Object -examples
+Request Body Object -requestBodies
+Header Object - headers
+Security Scheme Object - securitySchemes
+Link Object - links
+Callback Object - callbacks
+
+Then if no local declaration match system should follow normal reference object resolution rules.
+
+#### Array shortcut extension
+
+It is often handy to define an array of elements with a short concise syntax. We support this usecase with the following shortcut:
+
+```yaml
+application/json:
+      schema: pet[]
+```
+in other words. If the referenced string ends with `[]` and is used in the context of `Schema Object` then this reference string may be replaced with yaml object with the  following structure:
+
+```yaml
+type: array
+items: pet
+```
+so our original example is equivalent to:
+
+```yaml
+application/json:
+      schema: 
+         type: array
+         items: pet
+```
+this rule may be applied recursively.
+
+
+
 #### <a name="schemaObject"></a>Schema Object
 
 The Schema Object allows the definition of input and output data types.
@@ -2271,6 +2349,8 @@ The following properties are taken from the JSON Schema definition but their def
 - not - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema.
 - items - Value MUST be an object and not an array. Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. `items` MUST be present if the `type` is `array`.
 - properties - Property definitions MUST be a [Schema Object](#schemaObject) and not a standard JSON Schema (inline or referenced).
+
+
 - additionalProperties - Value can be boolean or object. Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema.
 - description - [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation.
 - format - See [Data Type Formats](#dataTypeFormat) for further details. While relying on JSON Schema's defined formats, the OAS offers a few additional predefined formats.
@@ -3364,6 +3444,107 @@ Two examples of this:
 1. The [Paths Object](#pathsObject) MAY be empty. It may be counterintuitive, but this may tell the viewer that they got to the right place, but can't access any documentation. They'd still have access to the [Info Object](#infoObject) which may contain additional information regarding authentication.
 2. The [Path Item Object](#pathItemObject) MAY be empty. In this case, the viewer will be aware that the path exists, but will not be able to see any of its operations or parameters. This is different than hiding the path itself from the [Paths Object](#pathsObject), so the user will not be aware of its existence. This allows the documentation provider to finely control what the viewer can see.
 
+### Merge directives
+
+Merge directives is a very limited way to define templating of JSON/YAML data structures. It allows to merge object definition
+with templates. Merging is performed by the same algorithm as in [Overlays/Extensions](https://github.com/mulesoft-labs/OpenAPI-Specification/pull/3/files#diff-d1455f6edb807e38d88298c2361ec1e3R3644) framework, and is performed as preprocessing step after reference resolution.
+
+Definition:  Every element of JSON structure which contains `$merge` key like in following example
+
+
+```yaml
+$merge: 
+   $ref: String containing JSON Reference to the macro definition objects
+   $arguments:
+      kind: “pet”
+```
+
+is a subject to the merge operation. Which is performed by the following scheme:
+
+
+If value of `$merge` is an object:
+
+1. take a macro definition referenced in `$ref` property and perform template substitution as defined later
+2. merge result of template substitution with a base object containing `$merge`key as defined in [Overlays/Extensions](https://github.com/mulesoft-labs/OpenAPI-Specification/pull/3/files#diff-d1455f6edb807e38d88298c2361ec1e3R3644)
+
+If value of `$merge` is an array perform merge operation for each of array members. (Every array member should be an object and must have a valid $ref and $arguments properties)
+
+Example
+
+```yaml
+$merge:
+   $ref: #/components/macros/secured
+   $arguments:  { tokenType: "integer" } 
+description: returns an Account
+content:
+  application/json:
+  schema:
+     $ref: "#/components/schemas/Account
+ ```
+
+ where `some` is defined as:
+ ```yaml
+ - headers:
+      X-Token:
+          description: token
+          schema:
+             type: {{tokenType}}
+```
+will be merged into:
+
+```yaml
+ - headers:
+      X-Token:
+          description: token
+          schema:
+             type: integer
+description: returns an Account
+content:
+  application/json:
+  schema:
+     $ref: "#/components/schemas/Account
+ ```
+
+### Macro definition template subsitution
+
+Macro definition defines a template for merging operation. Macro definition can not contain `$merge` directives.
+
+Macro application requires arguments object and is performed in the following way: 
+a) Deep clone data structure containing macro definition. 
+b) Launch the following algorithm on top of the cloned data structure:
+
+If cloned node is an object (map):
+	1.  apply an algorithm recursively to each of map values 
+	2. for each of map entries if map entry value is a string, replace it with a result of template substitution
+
+If clone node is an array (sequence)
+	1.  apply an algorithm recursively to each of sequence elements
+	2. for each of array entries test if entry is a string and replace it with a result of template substitution
+
+Template substitution:  If string starts with “<<“ and ends with “>>” replace the string with the value of corresponding macro argument
+else for each occurrence  of placeholders ( “<<“ .* “>>) in the source string, replace each of them with string representation of corresponding macro argument. If there is no corresponding argument object element raise error and stop substitution.
+
+
+Example:
+
+```yaml
+items:
+  type: <<kind>>
+```
+argument object: `{ kind: pet }`
+
+result: 
+
+```yaml
+items:
+  type: pet
+```
+
+
+##### Restrictions on macro parameters   
+
+Only strings, booleans and numbers are allowed.
+
 ## <a name="revisionHistory"></a>Appendix A: Revision History
 
 Version   | Date       | Notes