From 3ec7b0d82c933f76dcd97cf3257cdf81f5b0187e Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Fri, 7 Nov 2025 14:16:38 -0500 Subject: [PATCH 01/12] feat: adds parameters for actions Signed-off-by: Vincent Biret --- schemas/v1.1-dev/schema.yaml | 34 +++++++++++++++++ versions/1.1.0-dev.md | 73 ++++++++++++++++++++++++++++++++++++ 2 files changed, 107 insertions(+) diff --git a/schemas/v1.1-dev/schema.yaml b/schemas/v1.1-dev/schema.yaml index 9e78075..10162d7 100644 --- a/schemas/v1.1-dev/schema.yaml +++ b/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 diff --git a/versions/1.1.0-dev.md b/versions/1.1.0-dev.md index edf82d1..8ec5ef5 100644 --- a/versions/1.1.0-dev.md +++ b/versions/1.1.0-dev.md @@ -118,6 +118,7 @@ This object represents one or more changes to be applied to the target document | 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. | | 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. | | 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`. | +| | [[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 | +| ---- | :----: | ---- | +| 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]+`. | +| 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. | +| 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. | +| 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. From 9c32a1fe4c7652aa655acfc1e75ac09b837c0798 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Fri, 7 Nov 2025 14:21:36 -0500 Subject: [PATCH 02/12] tests: adds failing tests for parameter object Signed-off-by: Vincent Biret --- .../fail/parameters-environment-with-values.yaml | 12 ++++++++++++ .../v1.1-dev/fail/parameters-inline-no-values.yaml | 9 +++++++++ .../fail/parameters-inline-with-separator.yaml | 13 +++++++++++++ tests/v1.1-dev/fail/parameters-missing-name.yaml | 11 +++++++++++ 4 files changed, 45 insertions(+) create mode 100644 tests/v1.1-dev/fail/parameters-environment-with-values.yaml create mode 100644 tests/v1.1-dev/fail/parameters-inline-no-values.yaml create mode 100644 tests/v1.1-dev/fail/parameters-inline-with-separator.yaml create mode 100644 tests/v1.1-dev/fail/parameters-missing-name.yaml diff --git a/tests/v1.1-dev/fail/parameters-environment-with-values.yaml b/tests/v1.1-dev/fail/parameters-environment-with-values.yaml new file mode 100644 index 0000000..5e6bbc4 --- /dev/null +++ b/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" \ No newline at end of file diff --git a/tests/v1.1-dev/fail/parameters-inline-no-values.yaml b/tests/v1.1-dev/fail/parameters-inline-no-values.yaml new file mode 100644 index 0000000..5bf7ee0 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/tests/v1.1-dev/fail/parameters-inline-with-separator.yaml b/tests/v1.1-dev/fail/parameters-inline-with-separator.yaml new file mode 100644 index 0000000..7c5f137 --- /dev/null +++ b/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" \ No newline at end of file diff --git a/tests/v1.1-dev/fail/parameters-missing-name.yaml b/tests/v1.1-dev/fail/parameters-missing-name.yaml new file mode 100644 index 0000000..6f3ea75 --- /dev/null +++ b/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" \ No newline at end of file From 8979e9f6651b958f108025da0dc28cb455b9da08 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Fri, 7 Nov 2025 14:27:27 -0500 Subject: [PATCH 03/12] tests: adds pass tests for parameter object Signed-off-by: Vincent Biret --- .../pass/parameters-environment-valid.yaml | 9 +++++++++ .../parameters-environment-with-separator.yaml | 10 ++++++++++ .../v1.1-dev/pass/parameters-inline-valid.yaml | 13 +++++++++++++ .../pass/parameters-multiple-valid.yaml | 18 ++++++++++++++++++ .../pass/parameters-with-extensions.yaml | 14 ++++++++++++++ 5 files changed, 64 insertions(+) create mode 100644 tests/v1.1-dev/pass/parameters-environment-valid.yaml create mode 100644 tests/v1.1-dev/pass/parameters-environment-with-separator.yaml create mode 100644 tests/v1.1-dev/pass/parameters-inline-valid.yaml create mode 100644 tests/v1.1-dev/pass/parameters-multiple-valid.yaml create mode 100644 tests/v1.1-dev/pass/parameters-with-extensions.yaml diff --git a/tests/v1.1-dev/pass/parameters-environment-valid.yaml b/tests/v1.1-dev/pass/parameters-environment-valid.yaml new file mode 100644 index 0000000..7dc9d71 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/tests/v1.1-dev/pass/parameters-environment-with-separator.yaml b/tests/v1.1-dev/pass/parameters-environment-with-separator.yaml new file mode 100644 index 0000000..b1e6cb0 --- /dev/null +++ b/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: "," \ No newline at end of file diff --git a/tests/v1.1-dev/pass/parameters-inline-valid.yaml b/tests/v1.1-dev/pass/parameters-inline-valid.yaml new file mode 100644 index 0000000..e62dcc4 --- /dev/null +++ b/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" \ No newline at end of file diff --git a/tests/v1.1-dev/pass/parameters-multiple-valid.yaml b/tests/v1.1-dev/pass/parameters-multiple-valid.yaml new file mode 100644 index 0000000..56ca7ae --- /dev/null +++ b/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: ";" \ No newline at end of file diff --git a/tests/v1.1-dev/pass/parameters-with-extensions.yaml b/tests/v1.1-dev/pass/parameters-with-extensions.yaml new file mode 100644 index 0000000..6b47a72 --- /dev/null +++ b/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 \ No newline at end of file From 84ef0bad84ae4a3178685573bbab732012f59f09 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Mon, 10 Nov 2025 09:09:42 -0500 Subject: [PATCH 04/12] docs: simplifies to default values Signed-off-by: Vincent Biret --- schemas/v1.1-dev/schema.yaml | 25 +++++-------------- .../fail/parameters-inline-no-values.yaml | 9 ------- .../parameters-inline-with-separator.yaml | 13 ---------- .../pass/parameters-environment-valid.yaml | 5 ++-- ...parameters-environment-with-separator.yaml | 3 +-- .../pass/parameters-multiple-valid.yaml | 5 +--- .../pass/parameters-with-extensions.yaml | 3 +-- versions/1.1.0-dev.md | 11 +++----- 8 files changed, 15 insertions(+), 59 deletions(-) delete mode 100644 tests/v1.1-dev/fail/parameters-inline-no-values.yaml delete mode 100644 tests/v1.1-dev/fail/parameters-inline-with-separator.yaml diff --git a/schemas/v1.1-dev/schema.yaml b/schemas/v1.1-dev/schema.yaml index 10162d7..cf541e5 100644 --- a/schemas/v1.1-dev/schema.yaml +++ b/schemas/v1.1-dev/schema.yaml @@ -71,25 +71,12 @@ $defs: 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 + defaultValues: + type: array + items: + type: string + separator: + type: string required: - name $ref: "#/$defs/specification-extensions" diff --git a/tests/v1.1-dev/fail/parameters-inline-no-values.yaml b/tests/v1.1-dev/fail/parameters-inline-no-values.yaml deleted file mode 100644 index 5bf7ee0..0000000 --- a/tests/v1.1-dev/fail/parameters-inline-no-values.yaml +++ /dev/null @@ -1,9 +0,0 @@ -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 \ No newline at end of file diff --git a/tests/v1.1-dev/fail/parameters-inline-with-separator.yaml b/tests/v1.1-dev/fail/parameters-inline-with-separator.yaml deleted file mode 100644 index 7c5f137..0000000 --- a/tests/v1.1-dev/fail/parameters-inline-with-separator.yaml +++ /dev/null @@ -1,13 +0,0 @@ -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" \ No newline at end of file diff --git a/tests/v1.1-dev/pass/parameters-environment-valid.yaml b/tests/v1.1-dev/pass/parameters-environment-valid.yaml index 7dc9d71..21912d3 100644 --- a/tests/v1.1-dev/pass/parameters-environment-valid.yaml +++ b/tests/v1.1-dev/pass/parameters-environment-valid.yaml @@ -1,9 +1,8 @@ overlay: 1.1.0 info: - title: Valid Parameters - Environment Source + title: Valid Parameters - Environment version: 1.0.0 actions: - target: $.paths.*.get parameters: - - name: envParam - source: environment \ No newline at end of file + - name: envParam \ No newline at end of file diff --git a/tests/v1.1-dev/pass/parameters-environment-with-separator.yaml b/tests/v1.1-dev/pass/parameters-environment-with-separator.yaml index b1e6cb0..bc020a6 100644 --- a/tests/v1.1-dev/pass/parameters-environment-with-separator.yaml +++ b/tests/v1.1-dev/pass/parameters-environment-with-separator.yaml @@ -1,10 +1,9 @@ overlay: 1.1.0 info: - title: Valid Parameters - Environment Source with Separator + title: Valid Parameters - Environment with Separator version: 1.0.0 actions: - target: $.paths.*.get parameters: - name: envParamWithSep - source: environment separator: "," \ No newline at end of file diff --git a/tests/v1.1-dev/pass/parameters-multiple-valid.yaml b/tests/v1.1-dev/pass/parameters-multiple-valid.yaml index 56ca7ae..caf1b93 100644 --- a/tests/v1.1-dev/pass/parameters-multiple-valid.yaml +++ b/tests/v1.1-dev/pass/parameters-multiple-valid.yaml @@ -6,13 +6,10 @@ actions: - target: $.paths.*.get parameters: - name: inlineParam - source: inline - values: + defaultValues: - "dev" - "staging" - "prod" - name: envParam1 - source: environment - name: envParam2 - source: environment separator: ";" \ No newline at end of file diff --git a/tests/v1.1-dev/pass/parameters-with-extensions.yaml b/tests/v1.1-dev/pass/parameters-with-extensions.yaml index 6b47a72..9ee41d4 100644 --- a/tests/v1.1-dev/pass/parameters-with-extensions.yaml +++ b/tests/v1.1-dev/pass/parameters-with-extensions.yaml @@ -6,8 +6,7 @@ actions: - target: $.paths.*.get parameters: - name: paramWithExt - source: inline - values: + defaultValues: - "value1" - "value2" x-custom-extension: "custom value" diff --git a/versions/1.1.0-dev.md b/versions/1.1.0-dev.md index 8ec5ef5..3464e80 100644 --- a/versions/1.1.0-dev.md +++ b/versions/1.1.0-dev.md @@ -151,9 +151,8 @@ The object represents parameters that can be used with actions. | Field Name | Type | Description | | ---- | :----: | ---- | | 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]+`. | -| 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. | -| 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. | -| 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. | +| defaultValues | `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. | +| separator | `string` | Defaults `undefined` (no splitting is applied). When defined, the separator is used to split the environment variable value and extra multiple values. | #### Parameter Expressions @@ -567,13 +566,11 @@ actions: target: '$.components.schemas["${foo}${bar}"]' parameters: - name: foo - source: inline - value: + defaultValues: - one - two - name: bar - source: inline - values: + defaultValues: - A - B update: From daaa64e15a7db9312298bc1ac3bac37b7bede4e7 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Mon, 10 Nov 2025 09:11:23 -0500 Subject: [PATCH 05/12] tests: removes extraneous source Signed-off-by: Vincent Biret --- tests/v1.1-dev/pass/parameters-inline-valid.yaml | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/tests/v1.1-dev/pass/parameters-inline-valid.yaml b/tests/v1.1-dev/pass/parameters-inline-valid.yaml index e62dcc4..5ab9940 100644 --- a/tests/v1.1-dev/pass/parameters-inline-valid.yaml +++ b/tests/v1.1-dev/pass/parameters-inline-valid.yaml @@ -1,13 +1,12 @@ overlay: 1.1.0 info: - title: Valid Parameters - Inline Source + title: Valid Parameters - Default values version: 1.0.0 actions: - target: $.paths.*.get parameters: - name: param1 - source: inline - values: + defaultValues: - "value1" - "value2" - "value3" \ No newline at end of file From 8e74d35a52fc1af634548384646f51bf233ec507 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Thu, 13 Nov 2025 12:14:19 -0500 Subject: [PATCH 06/12] docs: removes the separator docs: makes default values records as well Signed-off-by: Vincent Biret --- schemas/v1.1-dev/schema.yaml | 8 +++--- versions/1.1.0-dev.md | 51 ++++++++++++++++++++++-------------- 2 files changed, 36 insertions(+), 23 deletions(-) diff --git a/schemas/v1.1-dev/schema.yaml b/schemas/v1.1-dev/schema.yaml index cf541e5..99a7d3f 100644 --- a/schemas/v1.1-dev/schema.yaml +++ b/schemas/v1.1-dev/schema.yaml @@ -74,9 +74,11 @@ $defs: defaultValues: type: array items: - type: string - separator: - type: string + oneOf: + - type: string + - type: object + additionalProperties: + type: string required: - name $ref: "#/$defs/specification-extensions" diff --git a/versions/1.1.0-dev.md b/versions/1.1.0-dev.md index 4ed87b6..84d42d7 100644 --- a/versions/1.1.0-dev.md +++ b/versions/1.1.0-dev.md @@ -144,15 +144,22 @@ The object represents parameters that can be used with actions. | Field Name | Type | Description | | ---- | :----: | ---- | | 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]+`. | -| defaultValues | `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. | -| separator | `string` | Defaults `undefined` (no splitting is applied). When defined, the separator is used to split the environment variable value and extra multiple values. | +| defaultValues | `string[] or Record[]` | 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}`. ONLY parameter expressions with a matching parameter definition for the action MAY be replaced by their values. +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 @@ -565,19 +572,23 @@ info: title: Makes a matrix projection version: 1.0.0 actions: - - description: Adds component schema ${foo}${bar} - target: '$.components.schemas["${foo}${bar}"]' + - 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: - - A - - B + - description: a + target: ALPHA + - description: b + target: BETA update: - someProperty: "Fizz ${foo}${bar} buzz" + someProperty: "Fizz ${foo}-${bar.description} buzz" ``` Is equivalent to defining @@ -588,22 +599,22 @@ info: title: Makes a matrix projection version: 1.0.0 actions: - - description: Adds component schema oneA - target: '$.components.schemas["oneA"]' + - description: Adds component schema one-a + target: '$.components.schemas["oneALPHA"]' update: - someProperty: "Fizz oneA buzz" - - description: Adds component schema oneB - target: '$.components.schemas["oneB"]' + someProperty: "Fizz one-a buzz" + - description: Adds component schema one-b + target: '$.components.schemas["oneBETA"]' update: - someProperty: "Fizz oneB buzz" - - description: Adds component schema twoA - target: '$.components.schemas["twoA"]' + someProperty: "Fizz one-b buzz" + - description: Adds component schema two-a + target: '$.components.schemas["twoALPHA"]' update: - someProperty: "Fizz twoA buzz" - - description: Adds component schema twoB - target: '$.components.schemas["twoB"]' + someProperty: "Fizz two-a buzz" + - description: Adds component schema two-b + target: '$.components.schemas["twoBETA"]' update: - someProperty: "Fizz twoB buzz" + someProperty: "Fizz two-b buzz" ``` ### Specification Extensions From a10b0dc8cd3d7a37f3bb22d0b22cadddbddd1fc2 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Thu, 13 Nov 2025 12:19:25 -0500 Subject: [PATCH 07/12] tests: updates test values for the parameter separator removal tests: updates test values for mapping default values Signed-off-by: Vincent Biret --- .../fail/parameters-environment-with-values.yaml | 12 ------------ tests/v1.1-dev/fail/parameters-missing-name.yaml | 3 +-- .../fail/parameters-with-mixed-values.yaml | 13 +++++++++++++ .../fail/parameters-with-nested-objects.yaml | 15 +++++++++++++++ .../pass/parameters-default-values-mapping.yaml | 15 +++++++++++++++ ....yaml => parameters-default-values-valid.yaml} | 0 .../parameters-environment-with-separator.yaml | 9 --------- .../v1.1-dev/pass/parameters-multiple-valid.yaml | 3 +-- ...ml => parameters-no-default-values-valid.yaml} | 0 9 files changed, 45 insertions(+), 25 deletions(-) delete mode 100644 tests/v1.1-dev/fail/parameters-environment-with-values.yaml create mode 100644 tests/v1.1-dev/fail/parameters-with-mixed-values.yaml create mode 100644 tests/v1.1-dev/fail/parameters-with-nested-objects.yaml create mode 100644 tests/v1.1-dev/pass/parameters-default-values-mapping.yaml rename tests/v1.1-dev/pass/{parameters-inline-valid.yaml => parameters-default-values-valid.yaml} (100%) delete mode 100644 tests/v1.1-dev/pass/parameters-environment-with-separator.yaml rename tests/v1.1-dev/pass/{parameters-environment-valid.yaml => parameters-no-default-values-valid.yaml} (100%) diff --git a/tests/v1.1-dev/fail/parameters-environment-with-values.yaml b/tests/v1.1-dev/fail/parameters-environment-with-values.yaml deleted file mode 100644 index 5e6bbc4..0000000 --- a/tests/v1.1-dev/fail/parameters-environment-with-values.yaml +++ /dev/null @@ -1,12 +0,0 @@ -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" \ No newline at end of file diff --git a/tests/v1.1-dev/fail/parameters-missing-name.yaml b/tests/v1.1-dev/fail/parameters-missing-name.yaml index 6f3ea75..48ecbd2 100644 --- a/tests/v1.1-dev/fail/parameters-missing-name.yaml +++ b/tests/v1.1-dev/fail/parameters-missing-name.yaml @@ -5,7 +5,6 @@ info: actions: - target: $.paths.*.get parameters: - - source: inline - values: + - values: - "value1" - "value2" \ No newline at end of file diff --git a/tests/v1.1-dev/fail/parameters-with-mixed-values.yaml b/tests/v1.1-dev/fail/parameters-with-mixed-values.yaml new file mode 100644 index 0000000..c303d16 --- /dev/null +++ b/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" \ No newline at end of file diff --git a/tests/v1.1-dev/fail/parameters-with-nested-objects.yaml b/tests/v1.1-dev/fail/parameters-with-nested-objects.yaml new file mode 100644 index 0000000..4098757 --- /dev/null +++ b/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" \ No newline at end of file diff --git a/tests/v1.1-dev/pass/parameters-default-values-mapping.yaml b/tests/v1.1-dev/pass/parameters-default-values-mapping.yaml new file mode 100644 index 0000000..6984c1c --- /dev/null +++ b/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" \ No newline at end of file diff --git a/tests/v1.1-dev/pass/parameters-inline-valid.yaml b/tests/v1.1-dev/pass/parameters-default-values-valid.yaml similarity index 100% rename from tests/v1.1-dev/pass/parameters-inline-valid.yaml rename to tests/v1.1-dev/pass/parameters-default-values-valid.yaml diff --git a/tests/v1.1-dev/pass/parameters-environment-with-separator.yaml b/tests/v1.1-dev/pass/parameters-environment-with-separator.yaml deleted file mode 100644 index bc020a6..0000000 --- a/tests/v1.1-dev/pass/parameters-environment-with-separator.yaml +++ /dev/null @@ -1,9 +0,0 @@ -overlay: 1.1.0 -info: - title: Valid Parameters - Environment with Separator - version: 1.0.0 -actions: - - target: $.paths.*.get - parameters: - - name: envParamWithSep - separator: "," \ No newline at end of file diff --git a/tests/v1.1-dev/pass/parameters-multiple-valid.yaml b/tests/v1.1-dev/pass/parameters-multiple-valid.yaml index caf1b93..9d3d040 100644 --- a/tests/v1.1-dev/pass/parameters-multiple-valid.yaml +++ b/tests/v1.1-dev/pass/parameters-multiple-valid.yaml @@ -11,5 +11,4 @@ actions: - "staging" - "prod" - name: envParam1 - - name: envParam2 - separator: ";" \ No newline at end of file + - name: envParam2 \ No newline at end of file diff --git a/tests/v1.1-dev/pass/parameters-environment-valid.yaml b/tests/v1.1-dev/pass/parameters-no-default-values-valid.yaml similarity index 100% rename from tests/v1.1-dev/pass/parameters-environment-valid.yaml rename to tests/v1.1-dev/pass/parameters-no-default-values-valid.yaml From 1ae6e32a40a1dc3ae9b3146ec54b7e6dd17909b1 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Thu, 13 Nov 2025 15:46:38 -0500 Subject: [PATCH 08/12] Update versions/1.1.0-dev.md Co-authored-by: Ralf Handl --- versions/1.1.0-dev.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/1.1.0-dev.md b/versions/1.1.0-dev.md index 84d42d7..d478cb5 100644 --- a/versions/1.1.0-dev.md +++ b/versions/1.1.0-dev.md @@ -143,7 +143,7 @@ The object represents parameters that can be used with actions. | Field Name | Type | Description | | ---- | :----: | ---- | -| 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]+`. | +| 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]+`. | | defaultValues | `string[] or Record[]` | 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 From 0f15483df93d8ce3adfb5d23d40c9d9c16b93a53 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Thu, 13 Nov 2025 15:47:00 -0500 Subject: [PATCH 09/12] Update versions/1.1.0-dev.md Co-authored-by: Ralf Handl --- versions/1.1.0-dev.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/1.1.0-dev.md b/versions/1.1.0-dev.md index d478cb5..5cc254c 100644 --- a/versions/1.1.0-dev.md +++ b/versions/1.1.0-dev.md @@ -144,7 +144,7 @@ The object represents parameters that can be used with actions. | Field Name | Type | Description | | ---- | :----: | ---- | | 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]+`. | -| defaultValues | `string[] or Record[]` | 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. | +| 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 From 89eb5afb3058c89f342e658bb8042204b5c7594e Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Thu, 13 Nov 2025 15:48:26 -0500 Subject: [PATCH 10/12] Update versions/1.1.0-dev.md Co-authored-by: Ralf Handl --- versions/1.1.0-dev.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/1.1.0-dev.md b/versions/1.1.0-dev.md index 5cc254c..a849f7c 100644 --- a/versions/1.1.0-dev.md +++ b/versions/1.1.0-dev.md @@ -118,7 +118,7 @@ This object represents one or more changes to be applied to the target document | 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. | | 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. | | 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`. | -| | [[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`. | +| | [[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. From 012debdd219b9da72cb7b119b0d83b923ecadaf4 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Fri, 21 Nov 2025 10:21:51 -0500 Subject: [PATCH 11/12] nit: plural vs singular --- versions/1.1.0-dev.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/1.1.0-dev.md b/versions/1.1.0-dev.md index a849f7c..bdc19a6 100644 --- a/versions/1.1.0-dev.md +++ b/versions/1.1.0-dev.md @@ -137,7 +137,7 @@ This object MAY be extended with [Specification Extensions](#specification-exten ### Parameter Object -The object represents parameters that can be used with actions. +The object represents a parameter that can be used with actions. #### Fixed Fields From 68e13ea4d9830604f9a8f0959d13c65241d39c77 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Fri, 21 Nov 2025 10:22:13 -0500 Subject: [PATCH 12/12] fix: missing property name Co-authored-by: Mike Kistler --- versions/1.1.0-dev.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/1.1.0-dev.md b/versions/1.1.0-dev.md index bdc19a6..323d7d2 100644 --- a/versions/1.1.0-dev.md +++ b/versions/1.1.0-dev.md @@ -118,7 +118,7 @@ This object represents one or more changes to be applied to the target document | 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. | | 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. | | 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`. | -| | [[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`. | +| parameters | [[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.