feat: adds a parameter object for the action object

schemas/v1.1-dev/schema.yaml

@@ -56,10 +56,33 @@ $defs:
       remove:
         type: boolean
         default: false
+      parameters:
+        type: array
+        items:
+          $ref: "#/$defs/parameter-object"
+        uniqueItems: true
     required:
       - target
     $ref: "#/$defs/specification-extensions"
     unevaluatedProperties: false
+  parameter-object:
+    type: object
+    properties:
+      name:
+        type: string
+        matches: '^[a-zA-Z0-9]+$'
+      defaultValues:
+        type: array
+        items:
+          oneOf:
+            - type: string
+            - type: object
+              additionalProperties:
+                type: string
+    required:
+      - name
+    $ref: "#/$defs/specification-extensions"
+    unevaluatedProperties: false
   specification-extensions:
     patternProperties:
       ^x-: true

tests/v1.1-dev/fail/parameters-missing-name.yaml

@@ -0,0 +1,10 @@
+overlay: 1.1.0
+info:
+  title: Invalid Parameters - Missing Name
+  version: 1.0.0
+actions:
+  - target: $.paths.*.get
+    parameters:
+      - values: 
+          - "value1"
+          - "value2"

tests/v1.1-dev/fail/parameters-with-mixed-values.yaml

@@ -0,0 +1,13 @@
+overlay: 1.1.0
+info:
+  title: Invalid Parameters - Default Values with nested objects
+  version: 1.0.0
+actions:
+  - target: $.paths.*.get
+    parameters:
+      - name: testParam
+        defaultValues: 
+          - value1:
+              key1:
+                subKey2: "sub-value2"
+          - "value2"

tests/v1.1-dev/fail/parameters-with-nested-objects.yaml

@@ -0,0 +1,15 @@
+overlay: 1.1.0
+info:
+  title: Invalid Parameters - Default Values with nested objects
+  version: 1.0.0
+actions:
+  - target: $.paths.*.get
+    parameters:
+      - name: testParam
+        defaultValues: 
+          - value1:
+              key1:
+                subKey2: "sub-value2"
+          - value2:
+              key2:
+                subKey2: "sub-value2"

tests/v1.1-dev/pass/parameters-default-values-mapping.yaml

@@ -0,0 +1,15 @@
+overlay: 1.1.0
+info:
+  title: Valid Parameters - Default values mapping
+  version: 1.0.0
+actions:
+  - target: $.paths.*.get
+    parameters:
+      - name: param1
+        defaultValues: 
+          - key: "value1"
+            value: "VALUE1"
+          - key: "value2"
+            value: "VALUE2"
+          - key: "value3"
+            value: "VALUE3"

tests/v1.1-dev/pass/parameters-default-values-valid.yaml

@@ -0,0 +1,12 @@
+overlay: 1.1.0
+info:
+  title: Valid Parameters - Default values
+  version: 1.0.0
+actions:
+  - target: $.paths.*.get
+    parameters:
+      - name: param1
+        defaultValues: 
+          - "value1"
+          - "value2"
+          - "value3"

tests/v1.1-dev/pass/parameters-multiple-valid.yaml

@@ -0,0 +1,14 @@
+overlay: 1.1.0
+info:
+  title: Valid Parameters - Multiple Parameters
+  version: 1.0.0
+actions:
+  - target: $.paths.*.get
+    parameters:
+      - name: inlineParam
+        defaultValues: 
+          - "dev"
+          - "staging"
+          - "prod"
+      - name: envParam1
+      - name: envParam2

tests/v1.1-dev/pass/parameters-no-default-values-valid.yaml

@@ -0,0 +1,8 @@
+overlay: 1.1.0
+info:
+  title: Valid Parameters - Environment
+  version: 1.0.0
+actions:
+  - target: $.paths.*.get
+    parameters:
+      - name: envParam

tests/v1.1-dev/pass/parameters-with-extensions.yaml

@@ -0,0 +1,13 @@
+overlay: 1.1.0
+info:
+  title: Valid Parameters - With Extensions
+  version: 1.0.0
+actions:
+  - target: $.paths.*.get
+    parameters:
+      - name: paramWithExt
+        defaultValues: 
+          - "value1"
+          - "value2"
+        x-custom-extension: "custom value"
+        x-another-extension: 42

versions/1.1.0-dev.md

@@ -118,6 +118,7 @@ This object represents one or more changes to be applied to the target document
 | <a name="action-update"></a>update | Any | If the `target` selects object nodes, the value of this field MUST be an object with the properties and values to merge with each selected object. If the `target` selects array nodes, the value of this field MUST be an array to concatenate with each selected array, or an object or primitive value to append to each selected array. If the `target` selects primitive nodes, the value of this field MUST be a primitive value to replace each selected node. This field has no impact if the `remove` field of this action object is `true` or if the `copy` field contains a value. |
 | <a name="action-copy"></a>copy | `string` | A JSONPath expression selecting a single node to copy into the `target` nodes. If the `target` selects object nodes, the value of this field MUST be an object with the properties and values to merge with each selected object. If the `target` selects array nodes, the value of this field MUST be an array to concatenate with each selected array, or an object or primitive value to append to each selected array. If the `target` selects primitive nodes, the value of this field MUST be a primitive value to replace each selected node. This field has no impact if the `remove` field of this action object is `true` or if the `update` field contains a value. |
 | <a name="action-remove"></a>remove | `boolean` | A boolean value that indicates that each of the target nodes MUST be removed from the the map or array it is contained in. The default value is `false`. |
+| <a name="action-parameters"></a> | [[Parameter Object](#parameter-object)] | An array of parameter objects to use and expand the action definition. MAY contain zero or more parameters. Parameters MUST have unique names across the collection. Default `undefined`. |
 
 If the `target` JSONPath expression selects zero nodes, the action succeeds without changing the target document.
 If the `target` JSONPath expression selects two or more nodes for an `update` or `copy` action, the selected nodes MUST be either all objects or all arrays or all primitives.
@@ -134,6 +135,31 @@ The properties of the `update` or `copy` object MUST be compatible with the targ
 
 This object MAY be extended with [Specification Extensions](#specification-extensions).
 
+### Parameter Object
+
+The object represents parameters that can be used with actions.
+
+#### Fixed Fields
+
+| Field Name | Type | Description |
+| ---- | :----: | ---- |
+| <a name="parameter-name"></a>name | `string` | **REQUIRED** A name for the parameter that is unique per action. The name MUST match the following regular expression `[a-zA-Z-0-9]+`. |
+| <a name="parameter-default-values"></a>defaultValues | [`string`] or [Map(`string`, `string`] | The values to use in case the environment variable is not defined. MAY contain zero or more entries. When values contains multiple entries, the action is effectively projected for each of the entries of the parameter. If multiple parameters are defined for any given action, parameters effectively act as a matrix definition and the action should be projected across each dimension. |
+
+#### Parameter Expressions
+
+Parameter expressions MAY be used in any field defined by the Action Object except for parameters. The syntax for parameter expressions is the following `${parameter_name}` or `${parameter_name.value_key}` if the value is a record of strings. ONLY parameter expressions with a matching parameter definition for the action MAY be replaced by their values.
+
+If an action defines a parameter which resolves multiple values, the parameter acts as a dimension for the action, and the parameterized action is effectively projected into multiple resolved actions before they are being applied to the target document.
+
+#### Environment Variable values
+
+The environment variable MAY ONLY contain:
+
+- A simple string `foo`.
+- A JSON array of strings `["foo", "bar"]`.
+- A JSON array of records of strings `[{"description": "foo", "target": "FOO"}, {"description": "bar", "target": "BAR"}]`.
+
 ### Examples
 
 #### Structured Overlay Example
@@ -536,6 +562,61 @@ paths:
           description: OK
 ```
 
+#### Parameter example
+
+This example shows how action parameters can be used to define multiple actions from a single one.
+
+```yaml
+overlay: 1.1.0
+info:
+  title: Makes a matrix projection
+  version: 1.0.0
+actions:
+  - description: Adds component schema ${foo}-${bar.description}
+    target: '$.components.schemas["${foo}${bar.target}"]'
+    parameters:
+      - name: foo
+        # using simple strings as default values
+        defaultValues:
+          - one
+          - two
+      - name: bar
+        # using records as default values
+        defaultValues:
+          - description: a
+            target: ALPHA
+          - description: b
+            target: BETA
+    update:
+      someProperty: "Fizz ${foo}-${bar.description} buzz"
+```
+
+Is equivalent to defining
+
+```yaml
+overlay: 1.1.0
+info:
+  title: Makes a matrix projection
+  version: 1.0.0
+actions:
+  - description: Adds component schema one-a
+    target: '$.components.schemas["oneALPHA"]'
+    update:
+      someProperty: "Fizz one-a buzz"
+  - description: Adds component schema one-b
+    target: '$.components.schemas["oneBETA"]'
+    update:
+      someProperty: "Fizz one-b buzz"
+  - description: Adds component schema two-a
+    target: '$.components.schemas["twoALPHA"]'
+    update:
+      someProperty: "Fizz two-a buzz"
+  - description: Adds component schema two-b
+    target: '$.components.schemas["twoBETA"]'
+    update:
+      someProperty: "Fizz two-b buzz"
+```
+
 ### Specification Extensions
 
 While the Overlay Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.