feat: adds action templates and reusable actions

versions/1.2.0-dev.md

@@ -84,7 +84,8 @@ This is the root object of the [Overlay](#overlay).
 | <a name="overlay-version"></a>overlay | `string` | **REQUIRED**. This string MUST be the [version number](#versions) of the Overlay Specification that the Overlay document uses. The `overlay` field SHOULD be used by tooling to interpret the Overlay document. |
 | <a name="overlay-info"></a>info | [Info Object](#info-object) | **REQUIRED**. Provides metadata about the Overlay. The metadata MAY be used by tooling as required. |
 | <a name="overlay-extends"></a>extends | `string` | URI reference that identifies the target document (such as an [[OpenAPI]] document) this overlay applies to. |
-| <a name="overlay-actions"></a>actions | [[Action Object](#action-object)] | **REQUIRED** An ordered list of actions to be applied to the target document. The array MUST contain at least one value. |
+| <a name="overlay-actions"></a>actions | [[Action Object](#action-object) or [Action Template Reference Object](#action-template-reference-object) or [Action Reference Object](#action-reference-object)] | **REQUIRED** An ordered list of actions to be applied to the target document. The array MUST contain at least one value. |
+| <a name="overlay-components"></a>components | [Components Object](#components-object) | A set of components to reuse across the Overlay Document. Optional. |
 
 This object MAY be extended with [Specification Extensions](#specification-extensions).
 
@@ -128,6 +129,21 @@ The metadata MAY be used by the clients if needed.
 
 This object MAY be extended with [Specification Extensions](#specification-extensions).
 
+#### Components Object
+
+The object provides a set of components to be reused across the Overlay document.
+
+##### Fixed Fields
+
+| Field Name | Type | Description |
+| ---- | :----: | ---- |
+| <a name="component-action-templates"></a>actionTemplates | Map(`string`, [Action Template Object](#action-template-object)) | A key-value set of action templates to reference in the actions. Optional. |
+| <a name="component-actions"></a>actions | Map(`string`, [Action Object](#action-object) or [Action Template Reference Object](#action-template-reference-object)) | A key-value set of actions or action template references to use in the actions. Optional. |
+
+> Note: the target field for components actions is Optional.
+
+This object MAY be extended with [Specification Extensions](#specification-extensions).
+
 #### Action Object
 
 This object represents one or more changes to be applied to the target document at the locations defined by the target JSONPath expression.
@@ -157,6 +173,79 @@ The properties of the `update` or `copy` object MUST be compatible with the targ
 
 This object MAY be extended with [Specification Extensions](#specification-extensions).
 
+#### Action Template Object
+
+This object represents one or more changes to be applied to the target document at the locations defined by the target JSONPath expression and reused in one of more action references.
+
+##### Fixed fields
+
+| Field Name | Type | Description |
+| ---- | :----: | ---- |
+| <a name="action-template-parameters"></a>parameters | [[Action template parameter object](#action-template-parameter-object)] | A list of parameters to be used during  string literal replacement. Optional. |
+| <a name="action-template-environment-variables"></a>environmentVariables | [[Action template parameter object](#action-template-parameter-object)] | A list of environment variables to be used during  string literal replacement. Optional. |
+| Any field defined in the [action object](#action-object) | mixed | The [string literal replacement syntax](#string-literal-replacement-syntax) MAY be used for any of the fields, and the replacements MUST be evaluated as the template reference is being resolved. |
+
+This object MAY be extended with [Specification Extensions](#specification-extensions).
+
+#### Action Template Parameter Object
+
+##### Fixed fields
+
+| Field Name | Type | Description |
+| ---- | :----: | ---- |
+| <a name="action-template-parameter-name"></a>name | `string` | **REQUIRED** The name of the parameter, MUST match the key for the string literal replacement expression. |
+| <a name="action-template-parameter-default>default | Any | A default value for the parameter to use when no value is provided by the reference. Optional. |
+
+
+This object MAY be extended with [Specification Extensions](#specification-extensions).
+
+#### Action Reference Object
+
+##### Fixed fields
+
+| Field Name | Type | Description |
+| ---- | :----: | ---- |
+| <a name="action-reference-ref"></a>$ref | `string` | **REQUIRED** A valid reference to an action in the components section, represented as `#/components/actions/actionTemplateKey`. |
+| <a name="action-reference-target"></a>target | `string` | A RFC9535 JSONPath query expression selecting nodes in the target document and overrides the target defined in the referenced action. Optional when the resolved action defines a target, required when the resolved action does not. |
+
+#### Action Template Reference Object
+
+##### Fixed fields
+
+| Field Name | Type | Description |
+| ---- | :----: | ---- |
+| <a name="action-template-reference-ref"></a>$ref | `string` | **REQUIRED** A valid reference to an action template in the components section, represented as `#/components/actionTemplates/actionTemplateKey`. |
+| <a name="action-template-reference-parameter-values>parameterValues | `Map(string, Any)` | A set of values to use for the template parameters, the key MUST match the parameter name. Optional. |
+
+This object MAY be extended with [Specification Extensions](#specification-extensions).
+
+### String Literal Replacement Syntax
+
+The following string replacement syntax MAY be used:
+
+%source.key%
+
+Where **source** is a known source whose value MUST ONLY be **env** for environment variables, or **param** for parameters. The key MUST only contain the following characters A-Za-z0-9, contain at least one character and start with a letter.
+
+#### ABNF Notation
+
+```abnf
+replacement-string = "%" source "." key "%"
+source             = "env" / "param"
+key                = ALPHA *( ALPHA / DIGIT )
+```
+
+Where ALPHA and DIGIT rules are defined in [[RFC5234]].
+
+#### Environment Replacement Source
+
+When the environment replacement source is used, the key MUST match (case-sensitive) an environment variable defined for the process parsing the Overlay document. If the environment variable is not defined, the processor MAY either replace it with an empty string or return an error.
+
+#### Parameter Replacement Source
+
+When the parameter replacement source is used, the key MUST match (case-sensitive) a corresponding parameter defined for the action template.
+
+
 ### Examples
 
 #### Structured Overlay Example
@@ -559,6 +648,201 @@ paths:
           description: OK
 ```
 
+##### Action Reference Example
+
+###### Source Description
+
+```yaml
+openapi: 3.2.0
+info:
+  title: Example API
+  version: 1.0.0
+paths:
+  /items:
+    get:
+      responses:
+        200:
+          description: OK
+  /some-items:
+    delete:
+      responses:
+        200:
+          description: OK
+```
+
+###### Overlay
+
+```yaml
+overlay: 1.2.0
+info:
+  title: Use templates to insert error responses
+  version: 1.0.0
+components:
+  actions:
+    errorResponse:
+      update:
+        404:
+          description: Not Found
+          application/json:
+            schema:
+              type: object
+              properties:
+                message:
+                  type: string
+      description: Adds an error response to the %param.pathItem% path item %param.operation% operation
+actions:
+- $ref: '#/components/actions/errorResponse'
+  target: "$.paths['items'].get.responses"
+- $ref: '#/components/actions/errorResponse'
+  target: "$.paths['some-items'].delete.responses"
+```
+
+###### Result Description
+
+```yaml
+openapi: 3.2.0
+info:
+  title: Example API
+  version: 1.0.0
+paths:
+  /items:
+    get:
+      responses:
+        200:
+          description: OK
+        404:
+          description: Not Found
+          application/json:
+            schema:
+              type: object
+                properties:
+                  errorMessage:
+                    type: string
+  /some-items:
+    delete:
+      responses:
+        200:
+          description: OK
+        404:
+          description: Not Found
+          application/json:
+            schema:
+              type: object
+                properties:
+                  deleteErrorMessage:
+                    type: string
+```
+
+##### Action Template Example
+
+###### Source Description
+
+```yaml
+openapi: 3.2.0
+info:
+  title: Example API
+  version: 1.0.0
+paths:
+  /items:
+    get:
+      responses:
+        200:
+          description: OK
+  /some-items:
+    delete:
+      responses:
+        200:
+          description: OK
+```
+
+###### Overlay
+
+```yaml
+overlay: 1.2.0
+info:
+  title: Use templates to insert error responses
+  version: 1.0.0
+components:
+  actionTemplates:
+    errorResponse:
+      target: "$.paths['%param.pathItem%'].%param.operation%.responses"
+      update:
+        404:
+          description: Not Found
+          application/json:
+            schema:
+              type: object
+              properties:
+                '%param.propertyName%':
+                  type: string
+                stageName:
+                  type: string
+                  const: '%env.stageName%'
+      description: Adds an error response to the %param.pathItem% path item %param.operation% operation
+      parameters:
+      - name: pathItem
+      - name: operation
+        default: get
+      - name: propertyName
+        default: errorMessage
+      environmentVariables:
+      - name: stageName
+        default: dev
+actions:
+- $ref: '#/components/actionTemplates/errorResponse'
+  parameterValues:
+    pathItem: '/items'
+- $ref: '#/components/actionTemplates/errorResponse'
+  parameterValues:
+    pathItem: '/some-items'
+    operation: delete
+    propertyName: deleteErrorMessage
+```
+
+> Note: in this example, no value is set for the process environment variable "stageName".
+
+###### Result Description
+
+```yaml
+openapi: 3.2.0
+info:
+  title: Example API
+  version: 1.0.0
+paths:
+  /items:
+    get:
+      responses:
+        200:
+          description: OK
+        404:
+          description: Not Found
+          application/json:
+            schema:
+              type: object
+                properties:
+                  errorMessage:
+                    type: string
+                  stageName:
+                    type: string
+                    const: dev
+  /some-items:
+    delete:
+      responses:
+        200:
+          description: OK
+        404:
+          description: Not Found
+          application/json:
+            schema:
+              type: object
+                properties:
+                  deleteErrorMessage:
+                    type: string
+                  stageName:
+                    type: string
+                    const: dev
+```
+
 ### Specification Extensions
 
 While the Overlay Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.