OpenAPI-Specification
OpenAPI-Specification copied to clipboard
OAI
Draft proposal for experimental field
(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.
@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.
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.
Filed #3257 to revive and clarify our proposals process. Once we figure it out, we'll resolve this PR accordingly.
@OAI/tsc is this proposal, like PR #3286, better started as an x- field to test it out? (@davidjgoss there is a registry for such fields which @miqui is updating as it has been a bit under-utilized).
If so, it would seem like this document should be associated with that, rather than a proposal in this repo. If not, we will get to looking at the draft proposal process soon and can evaluate this once we've revived that process.
This is already "out there" as an extension (citation: https://github.com/search?q=%22x-experimental%3A+true%22&type=code), and there was quite a bit of engagement around the issues for it. Can we say what is needed for this to merit consideration for 3.2?
@lornajane oh nice! It... did not even occur to me to check 😅 🤦
Yeah, that seems like a good reason to at least accept the proposal into the repo (meaning merging this PR, assuming it is in alignment with the x- usage that's actually happening). We can then work from the merged proposal document on the actual spec change. At least I think that's how it's supposed to work?
For what it's worth, we use x-ibm-release-level with possible values of experimental, beta, and preview. It seems like it would be worth considering whether to combine this kind of annotation into a single enumeration property with deprecated and possibly some other values.
The x-experimental also shows up in the extensions dataset from 2021 https://github.com/Mermade/openapi-specification-extensions/blob/main/extensions/2021/extensions.tsv#L154 so it looks like it's actively in use. I also spot x-deprecated here and agree with @hudlow that we could consider covering more lifecycle states.
Reports of an API Lifecycle SIG have been greatly exaggerated, it looks like there's a repo and a slack channel but no activity since the setup a couple of years ago in either.
@davidjgoss Would you be able to revisit this proposal and make some of the proposed updates? I'm in support of us adopting this change.
@lornajane sure, I’ll try and get those changes done over the next few days or so.
(Thanks everyone for input.)