Adding Array shortcut

versions/4.0.0.md

@@ -2233,6 +2233,82 @@ $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 +2347,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.