feat: adds a parameter object for the action object

schemas/v1.1-dev/schema.yaml

@@ -56,10 +56,44 @@ $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]+$'
+    oneOf:
+      - properties:
+          source:
+            const: inline
+          values:
+            type: array
+            items:
+              type: string
+            uniqueItems: true
+        required:
+          - source
+          - values
+      - properties:
+          source:
+            const: environment
+          separator:
+            type: string
+        required:
+          - source
+    required:
+      - name
+    $ref: "#/$defs/specification-extensions"
+    unevaluatedProperties: false
   specification-extensions:
     patternProperties:
       ^x-: true

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

@@ -0,0 +1,12 @@
+overlay: 1.1.0
+info:
+  title: Invalid Parameters - Environment Source with Values
+  version: 1.0.0
+actions:
+  - target: $.paths.*.get
+    parameters:
+      - name: testParam
+        source: environment
+        values: 
+          - "value1"
+          - "value2"

tests/v1.1-dev/fail/parameters-inline-no-values.yaml

@@ -0,0 +1,9 @@
+overlay: 1.1.0
+info:
+  title: Invalid Parameters - Inline Source without Values
+  version: 1.0.0
+actions:
+  - target: $.paths.*.get
+    parameters:
+      - name: testParam
+        source: inline

tests/v1.1-dev/fail/parameters-inline-with-separator.yaml

@@ -0,0 +1,13 @@
+overlay: 1.1.0
+info:
+  title: Invalid Parameters - Inline Source with Separator
+  version: 1.0.0
+actions:
+  - target: $.paths.*.get
+    parameters:
+      - name: testParam
+        source: inline
+        separator: ","
+        values: 
+          - "value1"
+          - "value2"

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

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

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

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

tests/v1.1-dev/pass/parameters-environment-with-separator.yaml

@@ -0,0 +1,10 @@
+overlay: 1.1.0
+info:
+  title: Valid Parameters - Environment Source with Separator
+  version: 1.0.0
+actions:
+  - target: $.paths.*.get
+    parameters:
+      - name: envParamWithSep
+        source: environment
+        separator: ","

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

@@ -0,0 +1,13 @@
+overlay: 1.1.0
+info:
+  title: Valid Parameters - Inline Source
+  version: 1.0.0
+actions:
+  - target: $.paths.*.get
+    parameters:
+      - name: param1
+        source: inline
+        values: 
+          - "value1"
+          - "value2"
+          - "value3"

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

@@ -0,0 +1,18 @@
+overlay: 1.1.0
+info:
+  title: Valid Parameters - Multiple Parameters
+  version: 1.0.0
+actions:
+  - target: $.paths.*.get
+    parameters:
+      - name: inlineParam
+        source: inline
+        values: 
+          - "dev"
+          - "staging"
+          - "prod"
+      - name: envParam1
+        source: environment
+      - name: envParam2
+        source: environment
+        separator: ";"

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

@@ -0,0 +1,14 @@
+overlay: 1.1.0
+info:
+  title: Valid Parameters - With Extensions
+  version: 1.0.0
+actions:
+  - target: $.paths.*.get
+    parameters:
+      - name: paramWithExt
+        source: inline
+        values: 
+          - "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 entry to append to each selected array. 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 an object node, the value of this field MUST be an object with the properties and values to merge with the selected node. If the `target` selects an array, the value of this field MUST be an entry to append to the array. 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 objects or arrays 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`. |
 
 The result of the `target` JSONPath expression MUST be zero or more objects or arrays (not primitive types or `null` values).
 If the `target` JSONPath expression selects zero nodes, the action succeeds without changing the target document.
@@ -141,6 +142,25 @@ The properties of the resolved `copy` object MUST be compatible with the target
 
 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 for the action the parameter is defined. The name MUST match the following regular expression `[a-zA-Z-0-9]+`. |
+| <a name="parameter-source"></a>source | `inline` or `environment` | **REQUIRED** Defines where the values for the parameters should be retrieved from. When `inline` is set, values are retrieved from the `values` property. When `environment` is set, the values are retrieved by the tool from environment variables. |
+| <a name="parameter-values"></a>values | `string[]` | **REQUIRED** when `source` is set to `inline`. 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. |
+| <a name="parameter-separator"></a>separator | `string` | Only applicable when `source` is set to `environment`. Defaults `undefined` (no splitting is applied). When defined, the separator is used to split the environment variable value and extra multiple values. |
+
+#### 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}`. 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.
+
 ### Examples
 
 #### Structured Overlay Example
@@ -533,6 +553,59 @@ 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}
+    target: '$.components.schemas["${foo}${bar}"]'
+    parameters:
+      - name: foo
+        source: inline
+        value:
+          - one
+          - two
+      - name: bar
+        source: inline
+        values:
+          - A
+          - B
+    update:
+      someProperty: "Fizz ${foo}${bar} 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 oneA
+    target: '$.components.schemas["oneA"]'
+    update:
+      someProperty: "Fizz oneA buzz"
+  - description: Adds component schema oneB
+    target: '$.components.schemas["oneB"]'
+    update:
+      someProperty: "Fizz oneB buzz"
+  - description: Adds component schema twoA
+    target: '$.components.schemas["twoA"]'
+    update:
+      someProperty: "Fizz twoA buzz"
+  - description: Adds component schema twoB
+    target: '$.components.schemas["twoB"]'
+    update:
+      someProperty: "Fizz twoB 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.