Draft proposal for experimental field #2386
Conversation
Thanks for the PR and making it through the proposals template! Just some thoughts.
proposals/005_Experimental.md
Outdated
| A new boolean field named `experimental`, defaulting to `experimental`, is added to: | ||
|
|
||
| - Operation | ||
| - Schema |
There was a problem hiding this comment.
I wonder whether adding the experimental field to higher level objects (such as parameter, requestBody and response) and dropping it from schema would work better? It might resolve the 'unanswered question' about experimental schema use in non-experimental operations.
There was a problem hiding this comment.
I'd missed parameter - have added that now, with a qualifier that it couldn't be used with with in: pathrequired: true since adding a new required parameter is a breaking change.
There was a problem hiding this comment.
I see your point about schema, I agree removing it from there would simplify. I'm not sure I understand how putting on requestBody and response instead would alleviate though, could you elaborate?
One use case I've had come up is having a subset of an object be experimental, like "we've added some more detail to this response, we're not totally sure about it yet but the rest of it remains stable in the meantime", so it would be a shame not to cover that, but perhaps a leaner way to introduce the concept initially?
proposals/005_Experimental.md
Outdated
| - _Specification extensions_ - publishers could add an extension in their own domain, but the benefit of the metadata being available to downstream tools (including those used by consumers, not just publishers) would be lost. | ||
| - _Tags_ - as above, but this also gets to mixing other kinds of metadata in with resource taxonomy, which seems wrong. | ||
| - _Different API_ - this would be the least messy from a technical perspective - maintain a completely separate API for experimental items, and then "promote" them to the main API once they are considered stable. This has increased overhead for publishers and consumers, and could also reduce the likelihood of getting feedback on, and early uptake of, experimental items if they are segregated in a different place altogether. | ||
|
|
There was a problem hiding this comment.
Can we add a note about use of overlays as a potential alternative? A semver-versioned base OAS document with one-or-more overlays labelled 'experimental' might meet the use-case too.
There was a problem hiding this comment.
Overlays looks very interesting! I do think it could work although perhaps more complex to implement against. Added an item to the alternatives section.
|
@MikeRalphson thanks for the feedback and apologies for taking a while to follow up! I've made some edits and responded inline. |
|
As a result of #2604 the filename for this proposal should change to use a dated prefix. Please could you update this PR to match? You can use the original PR date. Apologies for the extra work. |
|
@MikeRalphson no problem, that's done. |
|
Since this PR was submitted, we've created some special interest groups (SIGs), and one of them is planning to address the lifecycle, which I think this falls into. There isn't a lot of traction yet, and we're still working out how the group will actually operate, but I'd also suggest we use Discussions, either in the spec repo (this one) or possibly around the new repo linked above. There are some similarities to #1973 worth noting, as well. (Thanks @darrelmiller for flagging this proposal to the nascent lifecycle SIG!) |
|
Thanks @earth2marsh, that looks interesting. What would be the right next step for this PR? |
|
TBH, I'm not sure. I think as the lifecycle SIG gets traction, that this would be the basis of a discussion there where the overall lifecycle issues are considered? I'm not sure anyone has stepped up to run it yet, but I plan to stay involved and will flag this (and reach out) once it begins getting momentum. |
(Not sure if this is the best place/right way to start this conversation, but would be interested in feedback.)
TLDR: a way to include items in an API but marked as "experimental" to set expectations that they could change or go away, and that wouldn't be a "breaking change" in semver terms.