Adds a copy action

[baywet]

fixes #146
fixes #121
closes #140

Hi everyone,
I've tried to get to the simplest common denominator, and incorporate some of the feedback that was already provided:

• We want the ability to use what's already in the document to update the document.
• We want single purpose actions, that are mutually exclusive, atomic, and can be combined like lego bricks.
• We want our "action keywords" to be verbs.

I'm proposing to add a copy field to the action, that's mutually exclusive with remove or update. It's functionally equivalent to the update field except that it uses a JSON path to source the JSON Node instead of defining it inline.

I know there was some additional thinking about templating expressions, sourcing from env variables etc... But I think those can be considered orthogonal and be added in a separate PR by their champions. I'd like to get the smallest possible unit that brings a meaningful contribution through.

As an image is better than a thousand words, here are a couple of examples.

Copying a node to a node that already exists

overlay: 1.1.0
info:
  title: Merge an existing path item with another one
  version: 1.0.0
actions:
  - target: '$.paths["/bar"]'
    copy:  '$.paths["/foo"]'

Here the existing foo path item properties are being copied to the bar path item.

Copying a node to a node that DOES NOT already exists

overlay: 1.1.0
info:
  title: Merge an existing path item with another one, ensuring the target exists
  version: 1.0.0
actions:
  - target: '$.paths'
    update: { "bar": {} }
  - target: '$.paths["/bar"]'
    copy:  '$.paths["/foo"]'

Moving an item

overlay: 1.1.0
info:
  title: Move an existing path item to another one
  version: 1.0.0
actions:
   # optionally add a remove action to ensure "a clean slate" for the bar path item
  - target: '$.paths'
    update: { "bar": {} }
  - target: '$.paths["/bar"]'
    copy:  '$.paths["/foo"]'
  - target: '$.paths["/foo"]'
    remove: true

A couple of todos if that gets consensus:

• We need to stand up a v1.1-dev branch, and this needs to be rebased
• We need to add an example in the spec
• We need to update the schema
• We need to add some tests
• Editorial information (version, table, etc...) need to be applied

[baywet]

CC @ThomasRooney @lornajane @mikeschinkel

[baywet]

Here is an experimental implementation, it was fairly straightforward :)
BinkyLabs/openapi-overlays-dotnet#105

[ThomasRooney]

I personally really like this. It's simple nomenclature and implementation.

Annecdotally to me the alternative approach of using runtime expressions is more powerful in some ways, but also limiting in others. We've been using them at Speakeasy to represent complex concepts in Arazzo but unfortunately we've had to build escape hatches for places where they don't work (specifically the lack of conditionals). I'd propose we accept this as a minor version bump, and do that as an independent addition to this change as part of future work given a set of differing use-cases.

[mikekistler]

cc: @RobertCraigie @yjp20

Would be great to get your feedback on this one.

[lornajane]

Really I would like the "make a 1.1-dev branch" changes in a different pull request from the "add a copy action" changes. They are different things.

[baywet]

Really I would like the "make a 1.1-dev branch" changes in a different pull request from the "add a copy action" changes. They are different things.

@lornajane Are you referring to the unit tests infrastructure changes? Or would you like me to target a different branch all together?

[RobertCraigie]

Thanks for the ping @mikekistler! Super excited to see this is being worked on :)

I'll note that as someone that is not deeply familiar with Overlays yet, on first glance it was not immediately clear to me which json path was the one being updated, but it did click very quickly after I actually thought about it.

It feels silly to write that out as it is pretty clear now but that was my initial reaction, so I'm curious if you considered another name for the operation to be super explicit? e.g. copy-from?

[ralfhandl]

Really I would like the "make a 1.1-dev branch" changes in a different pull request from the "add a copy action" changes. They are different things.

@lornajane Are you referring to the unit tests infrastructure changes? Or would you like me to target a different branch all together?

I‘d like to have a separate PR that

• creates the v1.1 schema and
• sets up its tests.

This PR should only contain

• spec changes to add „copy“
• schema changes directly related to the spec changes
• test cases for those schema changes.

[baywet]

I'll stand up a new PR for the 1.1-dev setup changes soon, and once we merge it, this one should get easier to review and I'll address the other comments. Sorry about the "mess" I iterated my way through the changes to get this PR in an as advanced state as possible.

[baywet]

There, I just pushed #180

[mikeschinkel]

@baywet — #justfyi I am working on an updated overlay.md to illustrate what I mentioned on the call today. I am adding some examples and changing some headings for consistency because with a table of examples the inconsistency stands out more. I also changed some text from passive to active voice because the ghost of my technical writing professor in university is always sitting on my shoulder commenting on my passive voice.

Hope to have this available very soon, though I am not 100% sure how to submit a PR to a PR. Should I submit a PR to baywet/Overlay-Specification/feat/copy-node and then mention that I did so here?

[baywet]

For anybody following along, thanks for bearing with us while we clean up the branches/versions story. I've just "temporary aligned" things before retargeting to main (pending on #183).
This now should be much easier to review for "just the copy stuff", we're down to 3 modified files in the diff view :) (from almost 40 this morning)

[philsturgeon]

Really nice and simple. Solves the issues well. Welcome addition to overlays. 🫡

[lornajane]

I think we could adjust the example content to tell more of a self-contained story so I added some suggestions but we're definitely close!

[ralfhandl]

Sorry, one more nit.

[lornajane]

This is in great shape! Thanks @baywet and also all the reviewers