From 5a3298bac3f2815c5e9e4ae71b6474dc40be650b Mon Sep 17 00:00:00 2001 From: Pavel Petrochenko Date: Mon, 19 Feb 2018 18:57:17 +0700 Subject: [PATCH 1/9] Update 4.0.0.md --- versions/4.0.0.md | 52 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) diff --git a/versions/4.0.0.md b/versions/4.0.0.md index 7c4d640c0e..8bd1b0cba2 100644 --- a/versions/4.0.0.md +++ b/versions/4.0.0.md @@ -2233,6 +2233,58 @@ $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. + + #### Schema Object The Schema Object allows the definition of input and output data types. From 20158e2d534e83aabbddace1909bb72e54a9cf93 Mon Sep 17 00:00:00 2001 From: Pavel Petrochenko Date: Mon, 19 Feb 2018 19:46:22 +0700 Subject: [PATCH 2/9] Update 4.0.0.md --- versions/4.0.0.md | 30 ++++++++++++++++++++++++++++-- 1 file changed, 28 insertions(+), 2 deletions(-) diff --git a/versions/4.0.0.md b/versions/4.0.0.md index 8bd1b0cba2..4e66d6d550 100644 --- a/versions/4.0.0.md +++ b/versions/4.0.0.md @@ -2233,7 +2233,7 @@ $ref: Pet.yaml $ref: definitions.yaml#/Pet ``` -###Reference object shortcuts +### 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 @@ -2266,7 +2266,7 @@ application/json: items: pet ``` -Resolution rules: +#### Resolution rules: when using reference object short cut, following resolution rules should be applied. @@ -2284,6 +2284,30 @@ 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. + #### Schema Object @@ -2323,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. From ce83b500a1f71a96547f03670552cec5b4c01482 Mon Sep 17 00:00:00 2001 From: Pavel Petrochenko Date: Mon, 19 Feb 2018 21:43:59 +0700 Subject: [PATCH 3/9] working on another version of merge --- versions/4.0.0.md | 72 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) diff --git a/versions/4.0.0.md b/versions/4.0.0.md index 4e66d6d550..713996e9e3 100644 --- a/versions/4.0.0.md +++ b/versions/4.0.0.md @@ -2308,6 +2308,78 @@ application/json: ``` this rule may be applied recursively. +Simple Macro + +Simple Macro is a very limited way to define templating JSON/YAML data structures: + +Examples: + +```yaml +items: + type: <> +``` + +```json +{ + items: { + type: “<>” + } +} +``` + +### Merge objects + +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 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: <> +``` +argument object: `{ kind: pet }` + +result: + +```yaml +items: + type: pet +``` + +Macro processing: + +Applying macro: + +```yaml +$merge: + $ref: String containing JSON Reference to the macro definition objects + $arguments: + kind: “pet” +``` + + +Merging is performed by the same algorithm as merging of overlays and extensions: + +https://github.com/mulesoft-labs/OpenAPI-Specification/pull/3/files#diff-d1455f6edb807e38d88298c2361ec1e3R3644 + + + + #### Schema Object From ce0d031a1a34927de192457d7d8c85542bb23170 Mon Sep 17 00:00:00 2001 From: Pavel Petrochenko Date: Mon, 19 Feb 2018 21:57:07 +0700 Subject: [PATCH 4/9] trying to improve this. --- versions/4.0.0.md | 36 ++++++++++++++++++++++-------------- 1 file changed, 22 insertions(+), 14 deletions(-) diff --git a/versions/4.0.0.md b/versions/4.0.0.md index 713996e9e3..27e8a8ecea 100644 --- a/versions/4.0.0.md +++ b/versions/4.0.0.md @@ -2308,9 +2308,21 @@ application/json: ``` this rule may be applied recursively. -Simple Macro +### Merge objects + +Merge objects 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 is a subject to the merge operation. + + +```yaml +$merge: + $ref: String containing JSON Reference to the macro definition objects + $arguments: + kind: “pet” +``` -Simple Macro is a very limited way to define templating JSON/YAML data structures: Examples: @@ -2321,17 +2333,19 @@ items: ```json { - items: { - type: “<>” + "items": { + "type": “<>” } } ``` -### Merge objects +### Macro definitions + +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 the cloned data structure: +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 @@ -2345,7 +2359,6 @@ Template substitution: If string starts with “<<“ and ends with “>>” re 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 @@ -2372,14 +2385,9 @@ $merge: kind: “pet” ``` +##### Restrictions on macro parameters -Merging is performed by the same algorithm as merging of overlays and extensions: - -https://github.com/mulesoft-labs/OpenAPI-Specification/pull/3/files#diff-d1455f6edb807e38d88298c2361ec1e3R3644 - - - - +Only strings, booleans and numbers are allowed. #### Schema Object From ba9f5ecaa3812d31c70738ad427bb9287f0a96d1 Mon Sep 17 00:00:00 2001 From: Pavel Petrochenko Date: Mon, 19 Feb 2018 22:18:03 +0700 Subject: [PATCH 5/9] Adding example, text is a little bit better now. --- versions/4.0.0.md | 56 ++++++++++++++++++++++++++++++++++++----------- 1 file changed, 43 insertions(+), 13 deletions(-) diff --git a/versions/4.0.0.md b/versions/4.0.0.md index 27e8a8ecea..3c7c5755fd 100644 --- a/versions/4.0.0.md +++ b/versions/4.0.0.md @@ -2304,7 +2304,7 @@ so our original example is equivalent to: application/json: schema: type: array - items: pet + items: pet ``` this rule may be applied recursively. @@ -2313,7 +2313,7 @@ this rule may be applied recursively. Merge objects 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 is a subject to the merge operation. +Definition: Every element of JSON structure which contains `$merge` key like in following example ```yaml @@ -2323,23 +2323,53 @@ $merge: kind: “pet” ``` +is a subject to the merge operation. Which is performed by the following scheme: -Examples: + +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 -items: - type: <> +$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: -```json -{ - "items": { - "type": “<>” - } -} -``` +```yaml + - headers: + X-Token: + description: token + schema: + type: integer +description: returns an Account +content: + application/json: + schema: + $ref: "#/components/schemas/Account + ``` -### Macro definitions +### Macro definition template subsitution Macro definition defines a template for merging operation. Macro definition can not contain `$merge` directives. From 5adedfa9df630128ac312edb0b367c09b7baebc6 Mon Sep 17 00:00:00 2001 From: Pavel Petrochenko Date: Mon, 19 Feb 2018 22:20:02 +0700 Subject: [PATCH 6/9] renaming to directives, adding to TOC --- versions/4.0.0.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/versions/4.0.0.md b/versions/4.0.0.md index 3c7c5755fd..562ccea8f7 100644 --- a/versions/4.0.0.md +++ b/versions/4.0.0.md @@ -51,6 +51,7 @@ An OpenAPI definition can then be used by documentation generation tools to disp - [Header Object](#headerObject) - [Tag Object](#tagObject) - [Reference Object](#referenceObject) + - [Merge directives](#merge-objects) - [Schema Object](#schemaObject) - [Discriminator Object](#discriminatorObject) - [XML Object](#xmlObject) @@ -2308,9 +2309,9 @@ application/json: ``` this rule may be applied recursively. -### Merge objects +### Merge directives -Merge objects is a very limited way to define templating of JSON/YAML data structures. It allows to merge object definition +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 From cf25b8a92af89f1991331ce62cff23cc859220ba Mon Sep 17 00:00:00 2001 From: Pavel Petrochenko Date: Mon, 19 Feb 2018 22:21:49 +0700 Subject: [PATCH 7/9] restructuring a bit. --- versions/4.0.0.md | 224 +++++++++++++++++++++++----------------------- 1 file changed, 113 insertions(+), 111 deletions(-) diff --git a/versions/4.0.0.md b/versions/4.0.0.md index 562ccea8f7..85bd7d3b3d 100644 --- a/versions/4.0.0.md +++ b/versions/4.0.0.md @@ -50,8 +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) - - [Merge directives](#merge-objects) + - [Reference Object](#referenceObject) - [Schema Object](#schemaObject) - [Discriminator Object](#discriminatorObject) - [XML Object](#xmlObject) @@ -61,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 directives](#merge-directives) - [Appendix A: Revision History](#revisionHistory) @@ -2309,116 +2309,7 @@ application/json: ``` this rule may be applied recursively. -### 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: <> -``` -argument object: `{ kind: pet }` - -result: - -```yaml -items: - type: pet -``` - -Macro processing: - -Applying macro: - -```yaml -$merge: - $ref: String containing JSON Reference to the macro definition objects - $arguments: - kind: “pet” -``` - -##### Restrictions on macro parameters - -Only strings, booleans and numbers are allowed. #### Schema Object @@ -3553,6 +3444,117 @@ 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: <> +``` +argument object: `{ kind: pet }` + +result: + +```yaml +items: + type: pet +``` + +Macro processing: + +Applying macro: + +```yaml +$merge: + $ref: String containing JSON Reference to the macro definition objects + $arguments: + kind: “pet” +``` + +##### Restrictions on macro parameters + +Only strings, booleans and numbers are allowed. + ## Appendix A: Revision History Version | Date | Notes From d71b483c9c70027ca103f0acb4928425454b2a9f Mon Sep 17 00:00:00 2001 From: Pavel Petrochenko Date: Mon, 19 Feb 2018 22:22:49 +0700 Subject: [PATCH 8/9] Update 4.0.0.md --- versions/4.0.0.md | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/versions/4.0.0.md b/versions/4.0.0.md index 85bd7d3b3d..bb4a92fba1 100644 --- a/versions/4.0.0.md +++ b/versions/4.0.0.md @@ -3540,16 +3540,6 @@ items: type: pet ``` -Macro processing: - -Applying macro: - -```yaml -$merge: - $ref: String containing JSON Reference to the macro definition objects - $arguments: - kind: “pet” -``` ##### Restrictions on macro parameters From d6bc594d1630a22d300917172bf468f77f195e0e Mon Sep 17 00:00:00 2001 From: Pavel Petrochenko Date: Mon, 19 Feb 2018 22:25:31 +0700 Subject: [PATCH 9/9] splitting to separate branch --- versions/4.0.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/4.0.0.md b/versions/4.0.0.md index bb4a92fba1..097149226d 100644 --- a/versions/4.0.0.md +++ b/versions/4.0.0.md @@ -60,7 +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 directives](#merge-directives) + - [Merge directive](#merge-directives) - [Appendix A: Revision History](#revisionHistory)