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

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

This pull request adds reusable actions.

closes #238

Reusable actions are a much simpler iteration of anything previously proposed/iterated on:

component actions that can define any field that are available in actions today EXCEPT FOR the target
reference objects that have at least $ref and target in the actions array
reference object MAY also override anything from the referenced reusable action (copy/update/remove/description)

This iteration is better than earlier proposals because it's as simple as we can possibly make it. (no matrix, no variables, no string interpolation, etc...)

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

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

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>

mikekistler

Looks good. 👍

I made some suggestions that I think are improvements, but will leave the decision to you . Feel free to ignore these if you think they are off the mark.

mikekistler

Sorry ... that should have been a Approve.

Co-authored-by: Mike Kistler <mikekistler@microsoft.com>

mikekistler

Looks good! 👍

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

lornajane

Had a more detailed pass at it this time, added a few comments for things we should take a second glance at (especially considering how much refactoring has been done on this one) but nothing fundamental I promise!

lornajane · 2026-06-07T15:52:40Z

We might want to update the Overlay section in Definitions to make it a bit less specific? Right now it says

An Overlay is a JSON or YAML structure containing an ordered list of Action Objects that are to be applied to the target document.

attempted an update via a8c1719

Happy to take better suggestions.

lornajane · 2026-06-07T15:53:53Z

+1. A Reusable Action Object has to be referenced by a Reusable Action Reference Object to have any effect on the OpenAPI description.
+
+#### Reusable Action Reference Object
+


Let's add a sentence or two about what a resusable action reference object is and what it's for before we describe its fields

added in 3515bf7

lornajane · 2026-06-07T16:41:46Z

@@ -0,0 +1,10 @@
+overlay: 1.2.0
+info:
+  title: Reusable action with empty fields


I don't think I understand this one (and therefore probably didn't understand an earlier case that I also commented on!). How can an action have empty fields and succeed? Also should the one action in the collection here include a $ref ?

Here we're simply testing the JSON schema. This tests that:

fields is required on the reusable action object

any field under fields is not required (because we use the same base schema as the actions, and that was not required, and requiring it now would be breaking)

Let me know if you have any additional comments or questions.

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

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

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

baywet · 2026-06-08T14:28:55Z

@lornajane thanks for the great suggestions here! I took the liberty of resolving the ones that I considered trivial. Let me know what you think!

mikekistler

Re-approving.

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

Comment thread versions/1.2.0-dev.md Outdated

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>

mikekistler reviewed Jun 3, 2026

View reviewed changes

Comment thread versions/1.2.0-dev.md Outdated

Comment thread versions/1.2.0-dev.md

Comment thread versions/1.2.0-dev.md Outdated

mikekistler previously approved these changes Jun 3, 2026

View reviewed changes

Apply suggestions from code review

fb4b8b0

Co-authored-by: Mike Kistler <mikekistler@microsoft.com>

baywet dismissed stale reviews from mikekistler and ralfhandl via fb4b8b0 June 3, 2026 14:53

mikekistler previously approved these changes Jun 3, 2026

View reviewed changes

ralfhandl reviewed Jun 4, 2026

View reviewed changes

Comment thread versions/1.2.0-dev.md

chore: formatting

5967b36

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

baywet dismissed mikekistler’s stale review via 5967b36 June 4, 2026 17:04

Merge branch 'main' into feat/action-templates

8ab502b

baywet requested review from handrews, mikekistler and ralfhandl June 4, 2026 17:05

Merge branch 'main' into feat/action-templates

e5d2008

ralfhandl reviewed Jun 5, 2026

View reviewed changes

Comment thread schemas/v1.2-dev/schema.yaml Outdated

fix: removes duplicate reference in schemas

e8e9441

baywet requested a review from ralfhandl June 5, 2026 16:35

ralfhandl previously approved these changes Jun 7, 2026

View reviewed changes

lornajane reviewed Jun 7, 2026

View reviewed changes

baywet and others added 5 commits June 8, 2026 09:52

fix: wrong ident for example

4f30a3d

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

fix: wrong indent for action description

9e4c18a

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

fix: adds missing content keyword

031eb9d

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

docs: adds a short description to reference object

3515bf7

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

fix: wrap reusable action fields in invalid ref fixtures

729daf0

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

baywet dismissed ralfhandl’s stale review via 729daf0 June 8, 2026 14:08

baywet and others added 2 commits June 8, 2026 10:17

fix: reference reusable actions in extension fixtures

66dcdb6

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

docs: makes the recap less specific to the data structure

a8c1719

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

baywet requested a review from lornajane June 8, 2026 14:29

mikekistler approved these changes Jun 8, 2026

View reviewed changes

		1. A Reusable Action Object has to be referenced by a Reusable Action Reference Object to have any effect on the OpenAPI description.

		#### Reusable Action Reference Object

Conversation

baywet commented Feb 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

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!

mikekistler left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mikekistler left a comment

Choose a reason for hiding this comment

Uh oh!

mikekistler left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

lornajane left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lornajane Jun 7, 2026

Choose a reason for hiding this comment

Uh oh!

baywet Jun 8, 2026

Choose a reason for hiding this comment

Uh oh!

lornajane Jun 7, 2026

Choose a reason for hiding this comment

Uh oh!

baywet Jun 8, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lornajane Jun 7, 2026

Choose a reason for hiding this comment

Uh oh!

baywet Jun 8, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

baywet commented Jun 8, 2026

Uh oh!

mikekistler left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

baywet commented Feb 18, 2026 •

edited

Loading