Overlay proposal #1864
Overlay proposal #1864
Conversation
|
Sorry to bikeshed, but I'm not really a fan of the name |
|
@MikeRalphson Your bikeshedding is welcome and you raise valid questions. We should address them and change the name appropriately. I just didn't want to block the other work while we debated the name. |
|
Sorry I have been out of pocket for a while. I am looking into the specifics of the Overlay proposal and can't find it here https://github.com/OAI/OpenAPI-Specification/tree/master/proposals . The alternative schema proposal is there, and the template for future proposals, but I don't see overlays. Sorry if I missed it. |
|
@namdeirf The proposal is now there. @MikeRalphson The proposals folder is intended to be long lived. It serves as a place to keep a record of why the change happened and the scenarios that it intends to address. Your point is valid that we should have metadata that indicates what version of the spec the proposal is targeted. At least the major version, maybe the minor but not the patch. In the future we could decide to create subfolders for spec versions to partition the proposals. However, I'm not sure that is desirable. Someone creating a proposal may not be aware of the future version timeline and the proposal may take a number of released versions before it is integrated. I apologize for not addressing this issue earlier, I had seen your comment and then lost where it was until I cam to merge overlays. |
| version: 1.0.0 | ||
| updates: | ||
| - target: "@" | ||
| value: |
There was a problem hiding this comment.
Bad indentation (it's repeated on every example).
There was a problem hiding this comment.
Sequences (aka arrays) don't need to be indented https://yaml.org/spec/1.2/spec.html#id2802662
Since people perceive the “-” indicator as indentation, nested block sequences may be indented by one less space to compensate
https://yaml.org/spec/1.2/spec.html#id2799181
There was a problem hiding this comment.
Mmm, I didn't mean the - target but the indentation on value.
There was a problem hiding this comment.
Dammit. Sorry about that. I'll fix it.
|
|
||
| #### <a name="overlayDocument"></a>Overlay Document | ||
|
|
||
| An overlay document contains a list of [Update Objects](#overlayUpdates) that are to be applied to the target document. Each [Update Object](#updateObject) has a `target` property and a `value` property. The `target` property is a [JMESPath](http://jmespath.org/specification.html) query that identifies what part of the target document is to be updated and the `value` property contains an object with the properties to be overlaid. |
|
|
||
| ## Backwards compatibility | ||
|
|
||
| Overlays will be described in a new specification that can be used alongside an OpenAPI Description, therefore there will be no compatibility issues for the initial release. Overlay documents can be used against OpenAPI v2 and v3 descriptions. |
There was a problem hiding this comment.
I'm glad to see this, though it might be good to only support v3 to help give people another reason to move to v3.
There was a problem hiding this comment.
I considered it. I just didn't like the idea of creating an arbitrary constraint that I couldn't really justify. I'm on the fence. I suspect if we tell people they can't people will do it anyway.
|
|
||
| - Tooling will need a JMESPath implementation. | ||
| - Large overlays may be slow to process. | ||
| - Multiple complex pattern based overlays may cause overlapping updates causing confusing outcomes. |
There was a problem hiding this comment.
The overlay order needs to be unambiguous. Moreover, previous overlays in a chain must be immutable. A change to an earlier overlay will likely ruin subsequent overlays. Perhaps an overlay can declare a hash of the document it is updating? This would probably need to be coupled with some kind of ordering convention in the overlay files.
There was a problem hiding this comment.
That last comment of mine is poorly worded. An Overlay document has an array of update objects. The order of applying those updates is defined based on the order of the array. Therefore within an Overlay document the order is well defined. However, there still could be overlapping updates. That could make the Overlay document tricky to understand. Best practice should be to try and avoid the situation.
Having multiple Overlay documents apply to a single OpenAPI description is a different challenge. Currently this is up to tooling to manage the order of application. I don't like the idea of linking or ordering Overlay documents explicitly in the document, but I could imagine the use of priority value that provides an ordering hint to tooling.
To improve the process around working on the overlay feature, the contents of the Overlay issue have been moved into a markdown file that lives in the proposals folder in the master branch. The goal is to bring this document to the point where it can be copied and pasted into the official spec when finalized. For overlays, this may be a different spec document than the OpenApi spec document.