Clearer `action` syntax

[lornajane]

Currently the action fields are:

• target
• description
• update
• remove

Having update and remove as siblings isn't great because if remove is "true" then update does nothing, they're quite exclusive. I'm sure there's a reason it was done like this, but I really can't tell what the reason is so I'm proposing that we instead do something like:

• target (as before)
• description (as before)
• type which can be "update" or "remove"
• update (as before, but only valid if type is update)

Feedback is very welcome on this idea!

[baywet]

With #150 this issue compounds.

I'm not a big fan of the type approach because it's fairly redundant/verbose, and each "action kind" only has a single field to date. I think making the fields mutually exclusive as I'm suggesting in #184 should be enough here. Thoughts?

[handrews]

@lornajane if we go with your approach, in the new fields I'd use value instead of update. That way if there is a future operator that also takes a value, it will work just as well.

[lornajane]

One thing I don't like about my suggested approach is how overloaded the value/update field becomes. Because each action is a slightly different structure

[ralfhandl]

With the copy action added, I'd interpret/adjust the proposal to

Every Action Object has the fields

• description
• targets (plural)
• action: one of remove, update, copy

The remove action does not have additional fields.

The update action has an additional field value.

The copy action has an additional field source (mirroring target).

No overloading of fields.

What am I missing?

[baywet]

@ralfhandl so the "actual action" would be a sub-node in this proposal? or only the field of the action object would vary?

In case of the former, I find it a bit odd to have an action field in an action object. Additionally, I'm not sure this is providing a ton of value to the user (besides the oneOf part), at the cost of having to nest things deeper/creating a broad breaking change.

[ralfhandl]

All fields are siblings, no nesting.

overlay: 2.0.0
info:
  title: Examples for new action syntax
  version: 0.0.0
actions:
  - description: Add description to `get` operation on path `/foo`
    targets: $.paths['/foo'].get
    action: update
    value:
      description: This is the new description
  - description: Delete parameters with name `dummy` from all `get` operations
    targets: $.paths.*.get.parameters[?@.name == 'dummy']
    action: remove
  - description: 'copies recursively all elements from the "items" path item to the new "some-items" path item without ensuring the node exists before the copy'
    targets: '$.paths["/some-items"]'
    action: copy
    source: '$.paths["/items"]'

And if you have a better name than action or type for the field whose value is the action's verb, please tell me 😎

Maybe method?

[baywet]

Thank you for the additional information. It's not at all what I had understood and I like this much better :)

I think it has the advantage of being less redundant than the initial proposal, and account for the copy action. I think method would make a nicer name here.