feat: adds reusable actions by baywet · Pull Request #296 · OAI/Overlay-Specification

baywet · 2026-02-18T18:36:24Z

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 · 2026-02-18T19:04:23Z

I like the general direction.

baywet · 2026-02-24T16:35:26Z

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.

Signed-off-by: Vincent Biret <vincentbiret@hotmail.com>

ralfhandl

Mostly wording and capitalization

versions/1.2.0-dev.md

Co-authored-by: Ralf Handl <ralf.handl@gmail.com>

versions/1.2.0-dev.md

Signed-off-by: Vincent Biret <vincentbiret@hotmail.com>

…rlay-Specification into feat/action-templates Signed-off-by: Vincent Biret <vincentbiret@hotmail.com>

Signed-off-by: Vincent Biret <vincentbiret@hotmail.com>

baywet · 2026-03-03T13:46:27Z

@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!

…ferences Signed-off-by: Vincent Biret <vincentbiret@hotmail.com>

versions/1.2.0-dev.md

baywet · 2026-04-02T18:58:38Z

Finalized the implementation of the current version of the spec over here BinkyLabs/openapi-overlays-dotnet#276

(some LLMs were hurt in the process)

ralfhandl

Only reviewed the examples.

tests/v1.2-dev/fail/action-parameters-invalid.yaml

schemas/v1.2-dev/schema.yaml

tests/v1.2-dev/fail/action-with-environment-variables-invalid.yaml

tests/v1.2-dev/fail/reusable-action-parameter-values-not-allowed.yaml

tests/v1.2-dev/pass/reusable-action-environment-variables.yaml

tests/v1.2-dev/pass/reusable-action-reference-without-target.yaml

Co-authored-by: Ralf Handl <ralf.handl@gmail.com>

Signed-off-by: Vincent Biret <vincentbiret@hotmail.com>

mikekistler

I think this is very close now. I left a few more comments about possible improvements.

versions/1.2.0-dev.md

Signed-off-by: Vincent Biret <vincentbiret@hotmail.com>

ralfhandl

Only minor suggestions

tests/v1.2-dev/fail/action-with-environment-variables-invalid.yaml

tests/v1.2-dev/fail/action-with-parameter-invalid.yaml

versions/1.2.0-dev.md

Co-authored-by: Ralf Handl <ralf.handl@gmail.com> Co-authored-by: Vincent Biret <vincentbiret@hotmail.com>

Signed-off-by: Vincent Biret <vincentbiret@hotmail.com>

…ect nodes Signed-off-by: Vincent Biret <vincentbiret@hotmail.com>

Signed-off-by: Vincent Biret <vincentbiret@hotmail.com>

baywet · 2026-04-08T15:36:14Z

Sharing some number from the refactor on our internal repos: we're seeing about 30% reduction on average. Of course that number highly depends on how repetitive your Overlay document is.

mikekistler

Looks good. 👍

I think this is a valuable addition to Overlays and will help expand their adoption.

I wish we could fix some of the terminology quirks we have discussed -- in particular "Reusable Action Objects" -- but I don't want to make perfect the enemy of the good.

feedback implemented

handrews

A few minor comments and questions.

versions/1.2.0-dev.md

handrews · 2026-04-08T19:32:28Z

versions/1.2.0-dev.md

+| ---- | :----: | ---- |
+| <a name="reusable-action-reference-ref"></a>$ref | `string` | **REQUIRED** A [same-document](https://www.rfc-editor.org/rfc/rfc3986.html#section-4.4) (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/`. Component action keys in this pointer MUST be encoded according to [[RFC6901], Section 3](https://www.rfc-editor.org/rfc/rfc6901#section-3). |
+| <a name="reusable-action-reference-parameter-values></a>parameterValues | `Map(string, string)` | A set of string values to use for the reusable action parameters, the key MUST match the parameter name. Optional. |
+| <a name="reusable-action-reference-action-fields"></a>Any field defined in the [Action Object](#action-object) | mixed | Any field defined in the [Action Object](#action-object) to be used as an override to the value resolved in the reusable action. The [string literal replacement syntax](#string-literal-replacement-syntax) MAY NOT be used for any of the fields. Optional. |


This seems to be missing the field name and type? I see this is true in the other Object where I commented on RFC2119 usage as well? I also don't see a field name in the schema? I am confused here, is this a fixed field, and if so what is its name?

This comment applies to line 218, I apparently missed when selecting lines 🤦

The goal here was to say something along the lines of: "any field that's defined for the action object, you can also use here", without duplicating those. But if you think a copy paste instead would make the reading easier, I do that instead, what do you think?

Please do not duplicate the fields, that will cause trouble later when fields are added to actions and not here.

Thank you for the input. How do we reword this better so what we mean here is obvious then?

@baywet this feels more like a "Patterned Fields" than a "Fixed Fields"? Also, I'm concerned about embedding an "any field..." in an object with fixed fields. It invites field name collision problems. Can we push this down under a field that would hold all of this stuff in its own namespace?

Aaaah the collision aspect is a good callout (from the operations in OpenAPI) I had not thought out. We could in theory create a "definition" field which would effectively be an Overlay Action Object (with all fields optional, and the string interpolation turned on)

What do you think?

(using definition here for lack of better term, to avoid having another thing called "action")

Seems like the right general idea, but definition has JSON Schema-ish re-use connotations... you could just call it fields?

Sure! Always happy to get better name suggestions.

Co-authored-by: Henry Andrews <andrews_henry@yahoo.com>

nasha4 · 2026-04-09T18:46:27Z

versions/1.2.0-dev.md

 | Field Name | Type | Description |
 | ---- | :----: | ---- |
-| <a name="reusable-action-reference-ref"></a>$ref | `string` | **REQUIRED** A [same-document](https://www.rfc-editor.org/rfc/rfc3986.html#section-4.4) (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/`. Component action keys in this pointer MUST be encoded according to [[RFC6901], Section 3](https://www.rfc-editor.org/rfc/rfc6901#section-3). |
+| <a name="reusable-action-reference-ref"></a>$ref | `string` | **REQUIRED** A [same-document](https://www.rfc-editor.org/rfc/rfc3986.html#section-4.4) (or fragment-only) relative URI reference, per RFC3986 §4.4, where that the fragment syntax is JSON Pointer with the pointer prefix restricted to `/components/actions/`. Component action keys in this pointer MUST be encoded according to [[RFC6901], Section 3](https://www.rfc-editor.org/rfc/rfc6901#section-3). |


where that the fragment syntax is JSON Pointer

"where the fragment is a JSON Pointer"
(If that is what you mean?)

baywet added this to the Release 1.2 milestone Feb 18, 2026

baywet requested review from handrews, karenetheridge, lornajane, mikekistler, mkistler and ralfhandl and removed request for mkistler February 18, 2026 18:37

baywet added 6 commits February 25, 2026 09:53

feat: adds string literal replacement syntax

38198c9

Signed-off-by: Vincent Biret <vincentbiret@hotmail.com>

feat: adds high level definitions for templates and templates parameters

74f3a40

Signed-off-by: Vincent Biret <vincentbiret@hotmail.com>

feat: adds the action template reference object

2f2fbcc

Signed-off-by: Vincent Biret <vincentbiret@hotmail.com>

docs: adds an example for the action templates

77d9e4f

Signed-off-by: Vincent Biret <vincentbiret@hotmail.com>

feat: adds reusable actions to the components

5633f57

Signed-off-by: Vincent Biret <vincentbiret@hotmail.com>

feat: adds environment variables template

06a21c9

Signed-off-by: Vincent Biret <vincentbiret@hotmail.com>

baywet force-pushed the feat/action-templates branch from e709bde to 06a21c9 Compare February 25, 2026 15:19

baywet changed the title ~~feat: adds action templates~~ feat: adds action templates and reusable actions Feb 25, 2026

ralfhandl reviewed Feb 25, 2026

View reviewed changes

baywet and others added 3 commits February 25, 2026 11:37

chore: capitalization fixes

553fca8

Co-authored-by: Ralf Handl <ralf.handl@gmail.com>

chore: typo fixes

9329227

Co-authored-by: Ralf Handl <ralf.handl@gmail.com>

fix: case sensitive environment variable

d01be1e

Co-authored-by: Ralf Handl <ralf.handl@gmail.com>

handrews previously requested changes Feb 25, 2026

View reviewed changes

versions/1.2.0-dev.md Outdated Show resolved Hide resolved

baywet requested a review from ralfhandl February 25, 2026 18:56

baywet added 3 commits March 3, 2026 08:33

feat: merges reusable actions

0b71e07

Signed-off-by: Vincent Biret <vincentbiret@hotmail.com>

Merge branch 'feat/action-templates' of https://github.com/baywet/Ove…

beeeab0

…rlay-Specification into feat/action-templates Signed-off-by: Vincent Biret <vincentbiret@hotmail.com>

fix: updates wording for references definition

e64846a

Signed-off-by: Vincent Biret <vincentbiret@hotmail.com>

baywet added 2 commits March 3, 2026 08:46

Merge branch 'main' into feat/action-templates

e5be862

fix: aligns wording for the action fields in template and template re…

3a58335

…ferences Signed-off-by: Vincent Biret <vincentbiret@hotmail.com>

baywet commented Apr 2, 2026

View reviewed changes

versions/1.2.0-dev.md Outdated Show resolved Hide resolved

ralfhandl reviewed Apr 5, 2026

View reviewed changes

baywet and others added 2 commits April 6, 2026 07:56

Apply suggestions from code review

f57ce30

Co-authored-by: Ralf Handl <ralf.handl@gmail.com>

chore: feedback updates for a number of tests

e03b60d

Signed-off-by: Vincent Biret <vincentbiret@hotmail.com>

baywet requested a review from ralfhandl April 6, 2026 13:24

fix: allow underscores in parameter names

ad8f5e8

Signed-off-by: Vincent Biret <vincentbiret@hotmail.com>

mikekistler reviewed Apr 6, 2026

View reviewed changes

versions/1.2.0-dev.md Outdated Show resolved Hide resolved

versions/1.2.0-dev.md Outdated Show resolved Hide resolved

versions/1.2.0-dev.md Outdated Show resolved Hide resolved

baywet added 2 commits April 6, 2026 12:50

fix: removes outdated note about optional fields

569cff0

Signed-off-by: Vincent Biret <vincentbiret@hotmail.com>

docs: better representation of the reusable action object

c04856d

Signed-off-by: Vincent Biret <vincentbiret@hotmail.com>

ralfhandl reviewed Apr 6, 2026

View reviewed changes

baywet and others added 2 commits April 7, 2026 10:17

chore: Apply suggestions from code review

caade0d

Co-authored-by: Ralf Handl <ralf.handl@gmail.com> Co-authored-by: Vincent Biret <vincentbiret@hotmail.com>

tests: removes duplicate test definition

fd729d5

Signed-off-by: Vincent Biret <vincentbiret@hotmail.com>

baywet requested review from mikekistler and ralfhandl April 7, 2026 14:20

baywet mentioned this pull request Apr 7, 2026

The extends field should support referencing OADs by their $self #310

Open

baywet added 3 commits April 7, 2026 13:47

fix: restrict parameters defaults and values to string

7d43013

Signed-off-by: Vincent Biret <vincentbiret@hotmail.com>

fix: restrict the string interpolation syntax to string fields of obj…

18ea3ee

…ect nodes Signed-off-by: Vincent Biret <vincentbiret@hotmail.com>

fix: adds encoding considerations for keys

11e4053

Signed-off-by: Vincent Biret <vincentbiret@hotmail.com>

baywet mentioned this pull request Apr 7, 2026

Update reusable actions preview to ensure the encoding of component actions BinkyLabs/openapi-overlays-dotnet#287

Closed

Copilot AI mentioned this pull request Apr 8, 2026

feat(reusable-actions): RFC 6901 encode component action keys in x-$ref pointers BinkyLabs/openapi-overlays-dotnet#291

Merged

ralfhandl previously approved these changes Apr 8, 2026

View reviewed changes

mikekistler previously approved these changes Apr 8, 2026

View reviewed changes

handrews suggested changes Apr 8, 2026

View reviewed changes

fix: wording suggestions

d0d9f75

Co-authored-by: Henry Andrews <andrews_henry@yahoo.com>

baywet dismissed stale reviews from mikekistler and ralfhandl via d0d9f75 April 9, 2026 11:08

nasha4 reviewed Apr 9, 2026

View reviewed changes

Conversation

baywet commented Feb 18, 2026

Uh oh!

ralfhandl commented Feb 18, 2026

Uh oh!

baywet commented Feb 24, 2026

Uh oh!

ralfhandl left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

baywet commented Mar 3, 2026

Uh oh!

Uh oh!

baywet commented Apr 2, 2026

Uh oh!

ralfhandl left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mikekistler left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ralfhandl left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

baywet commented Apr 8, 2026

Uh oh!

mikekistler left a comment

Choose a reason for hiding this comment

Uh oh!

handrews left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

handrews Apr 9, 2026 •

edited

Loading