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)

[baywet]

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

@mikeschinkel Thanks for doing this, yet a PR to my feature branch should be fine if it's a large set of changes, I just pushed a few new things since the call FYI. If the changes are smaller, suggestions (comments with suggestion) in this PR can work as well.

[mikeschinkel]

@baywet — I am getting my IDE flagging x-oai-traits: ['paged'] as not valid and as I am not familiar with the syntax I asked ChatGPT and it said this, so you might want to look at it more closely?

The selector $.paths.*.get[[email protected]] for the x-oai-traits example currently defines ['paged'] (array), but the JSONPath selector checks for .paged, implying an object. It might not match as written. You may want to verify whether the intended shape was an object ({ paged: true }) or adjust the JSONPath for array membership.

[mikeschinkel]

@baywet — Here is the PR to your PR: baywet#1

I added a table listing the examples, and the rest of the changes followed from that to improve structure, clarity, and consistency (with no normative changes).

Summary of changeds

• Added a quick-reference table summarizing all examples
• Promoted Examples to a top-level non-normative section
• Added Array Move and Array Replace examples
• Standardized headings and ordering (Update, Copy, Move, Array)
• Adjusted anchors, grammar, and appendix order (File Naming → A, Revision History → B)

All content above ## Examples remains unchanged except to fix broken links.

[ralfhandl]

I am getting my IDE flagging x-oai-traits: ['paged'] as not valid

@mikeschinkel PR #118 contains a fix for that example.

[ralfhandl]

@baywet Please re-target to main, if possible

[baywet]

Thank you @ralfhandl for cleaning up the repo branches & al. I have now "manually rebased" this PR and it should be good for final review and merge.
@mikekistler and @lornajane I believe I have addressed all your comments in past iterations, let me know if I missed anything.
@mikeschinkel I've manually applied your suggestions that were directly related to this copy proposal, let me know if I missed anything. I suggest you open another PR now that branches/files are in place to get the other changes in.
@RobertCraigie I believe I have replied to your questions, let me know if I missed anything.

[ralfhandl]

One suggestion, one question

[philsturgeon]

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