Add compliant example sets to show expected behaviour

[lornajane]

These examples are taken from the test suite of https://github.com/lornajane/openapi-overlays-js (and with thanks to @MikeRalphson who helped with the tests originally!) to illustrate the expected outputs from applying particular Overlays to OpenAPI descriptions.

I think these examples could be improved/expanded, and I'm not sure if we should try to somehow standardise how whitespace/quotes work because they are most of the diff. Would it make sense to lint/format all the yaml? Advice welcome!

[ralfhandl]

we should try to somehow standardise how whitespace/quotes work because they are most of the diff

I'd run Prettier on the YAML files to minimize these differences.

[ralfhandl]

There should also be JSON inputs.

And some "mixed" inputs with OpenAPI JSON and Overlay YAML, and vice versa. Would the output format be determined by the format of the OpenAPI input? The spec doesn't tell.

[lornajane]

Fair enough. I don't think these are of a quality that we can publish for tests but from our conversation yesterday I thought we agreed that sharing whatever we had would be useful at this stage. Should I just close?

[ralfhandl]

Don't close, I think these are a good starting point. Even if they aren't complete yet, they are behavior that we expect from each implementation.

[ahx]

Hey @lornajane, I have a question about this and the related output.yaml:

The spec says:

If the target selects an object node, the value of this field MUST be an object with the properties and values to merge with the selected node. If the target selects an array, the value of this field MUST be an entry to append to the array.

The related part of the output expects "wildcard-done" to be added to the list of tags. But the target ($.paths.*.get) does not select an array. So should this be $.paths.*.get.tags instead and the tags field removed from update?

[lornajane]

I think the point here is that the target of the expression is an object (the path item object) and I'm amending a property of it. Does that help?

[ahx]

Sorry, I should probably just ask somewhere else about how to read the spec. The spec says "merge", which I understand like Object.assign(a, b) in JavaScript, where if properties defined in a will be overwritten by the same properties defined b. Array values would just be overwritten and not concatenanted as in the related output's "tags" array.

Is my understanding wrong?

[ahx]

This change is super useful, even in it's current state. I am building a ruby library against this right now ♥️

[lornajane]

@ahx thanks for the encouraging words! I've updated the PR and re-requested reviews for it.

[mikeschinkel]

This looks really great and would really like to see it approved.

[ralfhandl]

Can we normalize all YAML files so that there are no formatting variations (single/double/no quotes, empty lines, ...) and the diff between openapi.yaml and output.yaml is just the changes made by overlay.yaml?

[lornajane]

@ralfhandl Could you check if these were the changes you had in mind?

[ralfhandl]

Thanks, now I can just diff openapi.yamp and output.yaml and check whether it matches my expectation from overlay.yaml!

And they all do 😎