feat: adds action templates and reusable actions

[baywet]

This pull request adds action templates.

fixes #33
fixes #136
fixes #270

closes #238

This is another attempt to solve a scale limitation in the current specification. Action templates are better than the previous parameters proposal because:

• They do not introduce a matrix projection, people may use the template multiple times.
• They do not require "declaring" which environment variables to read in advance.
• They limit the string literal replacement to the templates, which does not impact how actions currently work.
• The template reference mechanism works like OpenAPI references.
• The template resolution mechanism can be isolated as a pre-processing step, and the resolved actions can then be fed to the existing code processing actions.
• It introduces a string literal replacement syntax which can be expanded upon for other sources or used at other places in the future.

The pull request is incomplete as it is, it's a draft, I want to collect feedback on the approach before making any further investments.

[ralfhandl]

I like the general direction.

[baywet]

Feedback from the meeting from both @lornajane and @ralfhandl :

• add a peer block to parameters for the environment variables, this allows to set defaults and "declare" which variables are used. But this declaration is optional.
• add a peer "actions" in the components, that's defined as everything except for the target. So people can specify the target on reference. Reusable actions may use action templates in turns.

[ralfhandl]

Mostly wording and capitalization

[handrews]

The correct way to define this is to say that the value is a same-document (or fragment-only) relative URI reference, per RFC3986 §4.4, and that the fragment syntax is JSON Pointer, with the pointer prefix restricted to /components/actions/.

It looks to me like the reference resolution mechanism here is delegation, as in JSON Schema draft 2020-12, and not replacment, as there is another field in this Object. That should be called out explicitly.

[baywet]

Thanks! I have updated the wording with your suggestion in the Action Templates Reference Object section. Let me know what you think!

[baywet]

@ralfhandl @lornajane I pushed another update a couple of minutes ago. I wasn't happy about the whole reusable actions vs action templates kind of thing. After chatting with @mikekistler internally I realized we could simply define a an action template reference object as "you can override anything from the resolved template in the reference" like JSON schema does to some extent. And keep things extra simple.

Let me know what you think!

[mikekistler]

I think this will be a very useful enhancement to overlays, but it needs some work to make it understandable to users.

I left some suggestions for wording changes and simplification. These are mainly as seed for discussion in our next Overlays SIG meeting.

[mikekistler]

Suggested change

	| <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-action-templates"></a>actionTemplates | Map(`string`, [Action Template Object](#action-template-object)) | A key-value set of action templates to reference in action template instantiations. Optional. |

[mikekistler]

Suggested change

	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.
	This object is a template that, when instantiated by an Action Template Instantiation, 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.

[mikekistler]

Suggested change

	An action template is similar to an action, but differs in two important ways:
	1. It may omit any action field, in particular the `target` field, as these may be supplied by the Action Template Instantiation.
	2. Any action field may employ string interpolation using variables specified in the `parameters` or `environmentVariables` fields.

[mikekistler]

I think calling this a "Reference Object" is confusing and inconsistent with other uses of this terminology. I suggest calling this an "Action Template Instantiation Object", as it's primary function is to "instantiate" a template.

[mikekistler]

I think we could eliminate the action fields here. They are already allowed in the template, so the action field in the template could be defined with a parameterize value, and the field value can then be passed in a parameter value. So eliminating the action fields here loses no functionality.