Fixes examples for compliance with RFC-9535

[mikekistler]

This PR makes a few minor fixes to the overlay examples to ensure they are compliant with RFC-9535.

I tested all the examples in the spec with Speakeasy's overlay playground and only these two had problems.

Note that any examples that use filters need

x-speakeasy-jsonpath: rfc9535

but I did not include that in the examples.

[lornajane]

Thanks!

[kevinswiber]

@mikekistler @gregsdennis Will this query work if we keep the original x-oai-traits example?

$.paths[[email protected]['x-oai-traits'][?@ == 'paged']].get

openapi: 3.1.0
info:
  title: API with a paged collection
  version: 1.0.0
paths:
  /items:
    get:
      x-oai-traits: ['paged']
      responses:
        200:
          description: OK

EDIT: It appears to work with Speakeasy's tooling.

[gregsdennis]

Yeah, that's compliant @kevinswiber.

[mikekistler]

Thanks @kevinswiber and @gregsdennis for puzzling out how to use the original x-oai-traits with array value. I've updated the PR to incorporate this.

[ralfhandl]

The spec says

If the target selects an array, the value of this field MUST be an entry to append to the array.

The original example appended a Parameter Object to an array of Parameter Objects, which feels correct.

The modified example appends a one-element array to an array, so I would expect the result be an array whose last element is the one-element array.

If we want "append to an array" to mean "concatenate two arrays", we should make that really clear in the text.

[kevinswiber]

@ralfhandl I don't think we do want that. I think the behavior you described is what I would expect. We had a whole issue and PR discussing arrays. I think it's #30?

[lornajane]

@ralfhandl can you take another look at this? Do we need to make the changes you requested?

[ralfhandl]

Well, that depends 😎

The Overlay specification says for action field update

If the target selects an array, the value of this field MUST be an entry to append to the array.

I would interpret this as

• If I want to add a Tag Object to the tags array, the value of update must be single the Tag Object I want to add.
• If I want to add two entries, I need two actions, each of which appends one entry to the array.

This interpretation is supported by the first Array Modification Example in the 1.0.0 spec.

However, both Bump.sh and Speakeasy require update to be an array with one or more entries, and this array is concatenated with the target.

If we want to keep the spec as it is now, the array modification example must not be changed, and we live with the fact that the two first implementations of the spec got array modification wrong.

If we want to make the example compatible with the two first implementations, we also must change the specification and say something like

If the target selects an array, the value of this field MUST be an array of entriesentry to append to the array.

or

If the target selects an array, the value of this field MUST be an arrayentry to concatenate withappend to the target array.

This however would be a breaking change and should be done in a new major version of the spec.

[lornajane]

I'm happy to approve this but we still have some requested changes to look at.