From 1072487a57d12c0629316bf69697916cc52926a5 Mon Sep 17 00:00:00 2001 From: David Goss Date: Sun, 16 Feb 2020 19:04:13 +0000 Subject: [PATCH 01/16] add proposal file from template --- proposals/005_Beta.md | 44 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) create mode 100644 proposals/005_Beta.md diff --git a/proposals/005_Beta.md b/proposals/005_Beta.md new file mode 100644 index 0000000000..00cb78d76f --- /dev/null +++ b/proposals/005_Beta.md @@ -0,0 +1,44 @@ +# Beta/Experimental marker + + +## Metadata + +|Tag |Value | +|---- | ---------------- | +|Proposal |[NNNN](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/{directory_or_file_name})| +|Authors|[Author 1](https://github.com/{author1}), [Author 2](https://github.com/{author2})| +|Review Manager |TBD | +|Status |Proposal, Draft, Promoted, or Abandoned| +|Implementations |[Click Here](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/{NNNN}/implementations.md)| +|Issues |[{issueid}](https://github.com/OAI/OpenAPI-Specification/issues/{Issueid})| +|Previous Revisions |[{revid}](https://github.com/OAI/OpenAPI-Specification/pull/{revid}) | + +## Change Log + +|Date |Responsible Party |Description | +|---- | ---------------- | ---------- | + +## Introduction + +A short description of what the feature is. Try to keep it to a single-paragraph "elevator pitch" so the reader understands what problem this proposal is addressing. + +## Motivation + +Describe the problems that this proposal seeks to address. If the problem is that some common pattern is currently hard to express, show how one can currently get a similar effect and describe its drawbacks. If it's completely new functionality that cannot be emulated, motivate why this new functionality would help OpenAPI developers create better code. + +## Proposed solution + +Describe your solution to the problem. Provide examples and describe how they work. Show how your solution is better than current workarounds: is it cleaner, safer, or more efficient? + +## Detailed design + +Describe the design of the solution in detail. This should include an exact description of the changes to the contents of the OpenAPI specification. That description should include a extract of each section of the OpenAPI specification which is impacted by the proposal with all proposed modifications applied. These extracts may be provided through additional files which are identified and described in this section. + +## Backwards compatibility + +Proposals should be structure so that they can be handled by existing OAS compliant software. Any potential issues should be identified and discussed. + +## Alternatives considered + +Describe alternative approaches to addressing the same problem, and why you chose this approach instead. + From 2f193299a27f7d2a908c91e57f11403b64e50346 Mon Sep 17 00:00:00 2001 From: David Goss Date: Mon, 17 Feb 2020 11:16:53 +0000 Subject: [PATCH 02/16] start to flesh out --- proposals/005_Beta.md | 73 ++++++++++++++++++++++++++++++++++++------- 1 file changed, 61 insertions(+), 12 deletions(-) diff --git a/proposals/005_Beta.md b/proposals/005_Beta.md index 00cb78d76f..2e83aead6f 100644 --- a/proposals/005_Beta.md +++ b/proposals/005_Beta.md @@ -5,13 +5,13 @@ |Tag |Value | |---- | ---------------- | -|Proposal |[NNNN](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/{directory_or_file_name})| -|Authors|[Author 1](https://github.com/{author1}), [Author 2](https://github.com/{author2})| +|Proposal |[005_Beta](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/005_Beta.md)| +|Authors|[David Goss](https://github.com/davidjgoss)| |Review Manager |TBD | -|Status |Proposal, Draft, Promoted, or Abandoned| -|Implementations |[Click Here](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/{NNNN}/implementations.md)| -|Issues |[{issueid}](https://github.com/OAI/OpenAPI-Specification/issues/{Issueid})| -|Previous Revisions |[{revid}](https://github.com/OAI/OpenAPI-Specification/pull/{revid}) | +|Status |Proposal| +|Implementations || +|Issues || +|Previous Revisions || ## Change Log @@ -20,25 +20,74 @@ ## Introduction -A short description of what the feature is. Try to keep it to a single-paragraph "elevator pitch" so the reader understands what problem this proposal is addressing. +A way to mark an aspect of the API as "beta" or "experimental", indicating that it is not yet a fully stable and supported part of the API. ## Motivation -Describe the problems that this proposal seeks to address. If the problem is that some common pattern is currently hard to express, show how one can currently get a similar effect and describe its drawbacks. If it's completely new functionality that cannot be emulated, motivate why this new functionality would help OpenAPI developers create better code. +Consider an API with two categories of thing in it: + +- Core, stable things, where we are committed to the ongoing stability and have no intention of making breaking changes +- New, experimental things, where we are getting them out there for feedback and early adopters, but they may change before we consider them to be in the first category + +These sit together fine in principle, but cause friction when trying to apply something like semver to the API as a whole. How do we make changes to the beta stuff - without bumping the major version several times a year and scaring our integrators - while also ensuring we can't make breaking changes to the core stuff we never want to break. ## Proposed solution -Describe your solution to the problem. Provide examples and describe how they work. Show how your solution is better than current workarounds: is it cleaner, safer, or more efficient? +Add a "beta" or "experimental" boolean field which specifies that an items in the API is not yet fully stable and supported, may change without a major version bump, and as such should be used with caution. + +_(I don't have a strong opinion about the naming - "beta" and "experimental" are two ideas - perhaps there is another word that conveys it better? For the rest of the proposal I'll refer to it as "beta" for brevity.)_ + +Downstream tools could then make use of this metadata: + +- Tools like swagger-ui could surface this in the documentation they generate so integrators are made aware. Beta items could also be filtered out of the documentation if desired. +- Tools ## Detailed design -Describe the design of the solution in detail. This should include an exact description of the changes to the contents of the OpenAPI specification. That description should include a extract of each section of the OpenAPI specification which is impacted by the proposal with all proposed modifications applied. These extracts may be provided through additional files which are identified and described in this section. +A new boolean field named `beta`, defaulting to `false`, is added to: + +- Operation +- Schema + +This specifies that the operation or schema is not yet stable and SHOULD be used with caution. + +### Specification changes + +### Operation Object + +... + +##### Fixed Fields + +... +Field Name | Type | Description +---|:---:|--- +...|...|... +beta | `boolean` | Specifies that an operation is in beta status, meaning it may change outside of the normal breaking change process. Consumers SHOULD use with caution. Default value is `false`. + +### Schema Object + +... + +##### Fixed Fields + +... +Field Name | Type | Description +---|:---:|--- +...|...|... +beta | `boolean` | Specifies that a schema is in beta status, meaning it may change outside of the normal breaking change process. Consumers SHOULD use with caution. Default value is `false`. + +### Unanswered Questions + +If an operation is not marked as beta, but it is used a schema which is, then it is implicitly also beta. Would this usage be considered invalid? ## Backwards compatibility -Proposals should be structure so that they can be handled by existing OAS compliant software. Any potential issues should be identified and discussed. +The `beta` field would default to false, meaning existing behaviour is preserved, and the new field is only used on an opt-in basis. ## Alternatives considered -Describe alternative approaches to addressing the same problem, and why you chose this approach instead. +- Specification extensions +- Tags +- Different API From 36427e4cf0cbda936282a615a95537da999ca5ef Mon Sep 17 00:00:00 2001 From: David Goss Date: Mon, 17 Feb 2020 11:20:20 +0000 Subject: [PATCH 03/16] try that table again --- proposals/005_Beta.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/proposals/005_Beta.md b/proposals/005_Beta.md index 2e83aead6f..34d051d129 100644 --- a/proposals/005_Beta.md +++ b/proposals/005_Beta.md @@ -59,10 +59,9 @@ This specifies that the operation or schema is not yet stable and SHOULD be used ##### Fixed Fields -... Field Name | Type | Description ---|:---:|--- -...|...|... +... | ... | ... beta | `boolean` | Specifies that an operation is in beta status, meaning it may change outside of the normal breaking change process. Consumers SHOULD use with caution. Default value is `false`. ### Schema Object @@ -71,10 +70,9 @@ Field Name | Type | Description ##### Fixed Fields -... Field Name | Type | Description ---|:---:|--- -...|...|... +... | ... | ... beta | `boolean` | Specifies that a schema is in beta status, meaning it may change outside of the normal breaking change process. Consumers SHOULD use with caution. Default value is `false`. ### Unanswered Questions From 201616c3c92fd52212d0ee36e06e9267862be7d3 Mon Sep 17 00:00:00 2001 From: David Goss Date: Mon, 17 Feb 2020 11:27:58 +0000 Subject: [PATCH 04/16] a bit more --- proposals/005_Beta.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/proposals/005_Beta.md b/proposals/005_Beta.md index 34d051d129..3cf6cbc389 100644 --- a/proposals/005_Beta.md +++ b/proposals/005_Beta.md @@ -33,14 +33,14 @@ These sit together fine in principle, but cause friction when trying to apply so ## Proposed solution -Add a "beta" or "experimental" boolean field which specifies that an items in the API is not yet fully stable and supported, may change without a major version bump, and as such should be used with caution. +Add a "beta" or "experimental" field which specifies that an items in the API is not yet fully stable and supported, may change without a major version bump, and as such should be used with caution. _(I don't have a strong opinion about the naming - "beta" and "experimental" are two ideas - perhaps there is another word that conveys it better? For the rest of the proposal I'll refer to it as "beta" for brevity.)_ Downstream tools could then make use of this metadata: - Tools like swagger-ui could surface this in the documentation they generate so integrators are made aware. Beta items could also be filtered out of the documentation if desired. -- Tools +- Tools for detecting and preventing breaking changes could take this into consideration when deciding whether a change is breaking. ## Detailed design @@ -77,7 +77,7 @@ Field Name | Type | Description ### Unanswered Questions -If an operation is not marked as beta, but it is used a schema which is, then it is implicitly also beta. Would this usage be considered invalid? +If an operation is not marked as beta, but it is using a schema which is (i.e. as its request object), then it is implicitly also beta. Would this usage be considered invalid? ## Backwards compatibility From 83c9c46645f16e748dbfed282ee95c69690f4872 Mon Sep 17 00:00:00 2001 From: David Goss Date: Mon, 17 Feb 2020 11:39:20 +0000 Subject: [PATCH 05/16] getting there --- proposals/005_Beta.md | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/proposals/005_Beta.md b/proposals/005_Beta.md index 3cf6cbc389..741f8afd7e 100644 --- a/proposals/005_Beta.md +++ b/proposals/005_Beta.md @@ -1,6 +1,5 @@ # Beta/Experimental marker - ## Metadata |Tag |Value | @@ -29,7 +28,7 @@ Consider an API with two categories of thing in it: - Core, stable things, where we are committed to the ongoing stability and have no intention of making breaking changes - New, experimental things, where we are getting them out there for feedback and early adopters, but they may change before we consider them to be in the first category -These sit together fine in principle, but cause friction when trying to apply something like semver to the API as a whole. How do we make changes to the beta stuff - without bumping the major version several times a year and scaring our integrators - while also ensuring we can't make breaking changes to the core stuff we never want to break. +These sit together fine in principle, but cause friction when trying to apply something like semver to the API as a whole. How do we make changes to the beta stuff - without bumping the major version several times a year and scaring consumers - while also ensuring we can't make breaking changes to the core stuff we never want to break. ## Proposed solution @@ -39,7 +38,7 @@ _(I don't have a strong opinion about the naming - "beta" and "experimental" are Downstream tools could then make use of this metadata: -- Tools like swagger-ui could surface this in the documentation they generate so integrators are made aware. Beta items could also be filtered out of the documentation if desired. +- Tools like swagger-ui could surface this in the documentation they generate so consumers are made aware. Beta items could also be filtered out of the documentation if desired. - Tools for detecting and preventing breaking changes could take this into consideration when deciding whether a change is breaking. ## Detailed design @@ -51,8 +50,6 @@ A new boolean field named `beta`, defaulting to `false`, is added to: This specifies that the operation or schema is not yet stable and SHOULD be used with caution. -### Specification changes - ### Operation Object ... @@ -77,7 +74,8 @@ Field Name | Type | Description ### Unanswered Questions -If an operation is not marked as beta, but it is using a schema which is (i.e. as its request object), then it is implicitly also beta. Would this usage be considered invalid? +- If an operation is not marked as beta, but it is using a schema which is (i.e. as its request object), then it is implicitly also beta. Would this usage be considered invalid? +- Should `beta` and `deprecated` be mutually exclusive? ## Backwards compatibility @@ -85,7 +83,7 @@ The `beta` field would default to false, meaning existing behaviour is preserved ## Alternatives considered -- Specification extensions -- Tags -- Different API +- _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 ill-advised. +- _Different API_ - this would be the least messy from a technical perspective - maintain a completely separate API for beta 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, beta items if they are segregated in a different place altogether. From b03e1b6d1389dd5a6b4e5be0067be6a73ceb424b Mon Sep 17 00:00:00 2001 From: David Goss Date: Mon, 17 Feb 2020 15:27:36 +0000 Subject: [PATCH 06/16] add example yaml --- proposals/005_Beta.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/proposals/005_Beta.md b/proposals/005_Beta.md index 741f8afd7e..066a317933 100644 --- a/proposals/005_Beta.md +++ b/proposals/005_Beta.md @@ -72,6 +72,26 @@ Field Name | Type | Description ... | ... | ... beta | `boolean` | Specifies that a schema is in beta status, meaning it may change outside of the normal breaking change process. Consumers SHOULD use with caution. Default value is `false`. +### Example Spec + +```yaml + /asset/constraints: + get: + tags: + - Asset + - Constraints + summary: Get a set of asset constraints + operationId: constraints + parameters: + - name: siteToken + in: query + description: Site token obtained from Site API + required: true + schema: + type: string + beta: true +``` + ### Unanswered Questions - If an operation is not marked as beta, but it is using a schema which is (i.e. as its request object), then it is implicitly also beta. Would this usage be considered invalid? From 245e9f49c8d1285173ed375ce8c83d5954882178 Mon Sep 17 00:00:00 2001 From: David Goss Date: Mon, 17 Feb 2020 15:35:46 +0000 Subject: [PATCH 07/16] prior art referencing typescript libs --- proposals/005_Beta.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/proposals/005_Beta.md b/proposals/005_Beta.md index 066a317933..7059cb45f6 100644 --- a/proposals/005_Beta.md +++ b/proposals/005_Beta.md @@ -91,6 +91,9 @@ Field Name | Type | Description type: string beta: true ``` +### Prior Art + +This kind of requirement is handled for TypeScript libraries by [api-extractor](https://api-extractor.com/pages/tsdoc/doc_comment_syntax/#release-tags) - they have both "alpha" and "beta" markers with a somewhat opinionated flow attached - I'm not sure that level of granularity is necessary. ### Unanswered Questions From 994fd3a3d0d6f8cd0f214ddea67c943f6a456ee9 Mon Sep 17 00:00:00 2001 From: David Goss Date: Mon, 17 Feb 2020 15:50:53 +0000 Subject: [PATCH 08/16] quote from api-extractor --- proposals/005_Beta.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/proposals/005_Beta.md b/proposals/005_Beta.md index 7059cb45f6..3608e7d884 100644 --- a/proposals/005_Beta.md +++ b/proposals/005_Beta.md @@ -93,7 +93,10 @@ Field Name | Type | Description ``` ### Prior Art -This kind of requirement is handled for TypeScript libraries by [api-extractor](https://api-extractor.com/pages/tsdoc/doc_comment_syntax/#release-tags) - they have both "alpha" and "beta" markers with a somewhat opinionated flow attached - I'm not sure that level of granularity is necessary. +This kind of requirement is handled for TypeScript libraries by [api-extractor](https://api-extractor.com/pages/tsdoc/doc_comment_syntax/#release-tags) - they have both "alpha" and "beta" markers with a somewhat opinionated flow attached - I'm not sure that level of granularity is necessary. But the "beta" and "public" ones map well to the motivations described here: + +> - **beta**: Indicates that an API item has been released as a preview or for experimental purposes. Third parties are encouraged to try it and provide feedback. However, a “beta” API should NOT be used in production, because it may be changed or removed in a future version. +> - **public**: Indicates that an API item has been officially released, and is now part of the supported contract for a package. If the SemVer versioning scheme is used, then the API signature cannot be changed without a MAJOR version increment. ### Unanswered Questions From bec991a0bfa1f36bd0ca048d7c36bbdea4db365f Mon Sep 17 00:00:00 2001 From: David Goss Date: Wed, 28 Oct 2020 11:26:18 +0000 Subject: [PATCH 09/16] rename and updates --- .../{005_Beta.md => 005_Experimental.md} | 36 +++++++++---------- 1 file changed, 18 insertions(+), 18 deletions(-) rename proposals/{005_Beta.md => 005_Experimental.md} (54%) diff --git a/proposals/005_Beta.md b/proposals/005_Experimental.md similarity index 54% rename from proposals/005_Beta.md rename to proposals/005_Experimental.md index 3608e7d884..c6428991a1 100644 --- a/proposals/005_Beta.md +++ b/proposals/005_Experimental.md @@ -1,10 +1,10 @@ -# Beta/Experimental marker +# Experimental marker ## Metadata |Tag |Value | |---- | ---------------- | -|Proposal |[005_Beta](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/005_Beta.md)| +|Proposal |[005_Experimental](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/005_Experimental.md)| |Authors|[David Goss](https://github.com/davidjgoss)| |Review Manager |TBD | |Status |Proposal| @@ -19,31 +19,31 @@ ## Introduction -A way to mark an aspect of the API as "beta" or "experimental", indicating that it is not yet a fully stable and supported part of the API. +A way to mark an aspect of the API as "experimental", indicating that it is not yet a fully stable and supported part of the API. ## Motivation Consider an API with two categories of thing in it: -- Core, stable things, where we are committed to the ongoing stability and have no intention of making breaking changes -- New, experimental things, where we are getting them out there for feedback and early adopters, but they may change before we consider them to be in the first category +- Core, stable things, where we are committed to the ongoing stability and have no intention of making breaking changes. +- New, experimental things, where we are getting them out there for feedback and early adopters, but they may change before we consider them to be in the first category, or even just get removed. -These sit together fine in principle, but cause friction when trying to apply something like semver to the API as a whole. How do we make changes to the beta stuff - without bumping the major version several times a year and scaring consumers - while also ensuring we can't make breaking changes to the core stuff we never want to break. +These sit together fine in principle, but cause friction when trying to apply something like semver to the API as a whole. How do we make changes to the experimental stuff - without bumping the major version several times a year and scaring consumers - while also ensuring we can't make breaking changes to the core stuff we never _want_ to break. ## Proposed solution -Add a "beta" or "experimental" field which specifies that an items in the API is not yet fully stable and supported, may change without a major version bump, and as such should be used with caution. +Add an "experimental" field which specifies that an items in the API is not yet fully stable and supported, may change or be removed without a major version bump, and as such should be used with caution. -_(I don't have a strong opinion about the naming - "beta" and "experimental" are two ideas - perhaps there is another word that conveys it better? For the rest of the proposal I'll refer to it as "beta" for brevity.)_ +_(I don't have a strong opinion about the naming - "beta" is another idea, though I think "experimental" does the job better in terms of being the most noncommital.)_ Downstream tools could then make use of this metadata: -- Tools like swagger-ui could surface this in the documentation they generate so consumers are made aware. Beta items could also be filtered out of the documentation if desired. +- Tools like swagger-ui could surface this in the documentation they generate so consumers are made aware. Experimental items could also be filtered out of the documentation if desired. - Tools for detecting and preventing breaking changes could take this into consideration when deciding whether a change is breaking. ## Detailed design -A new boolean field named `beta`, defaulting to `false`, is added to: +A new boolean field named `experimental`, defaulting to `experimental`, is added to: - Operation - Schema @@ -59,7 +59,7 @@ This specifies that the operation or schema is not yet stable and SHOULD be used Field Name | Type | Description ---|:---:|--- ... | ... | ... -beta | `boolean` | Specifies that an operation is in beta status, meaning it may change outside of the normal breaking change process. Consumers SHOULD use with caution. Default value is `false`. +experimental | `boolean` | Specifies that an operation is in experimental status, meaning it may change outside of the normal breaking change process. Consumers SHOULD use with caution. Default value is `false`. ### Schema Object @@ -70,7 +70,7 @@ Field Name | Type | Description Field Name | Type | Description ---|:---:|--- ... | ... | ... -beta | `boolean` | Specifies that a schema is in beta status, meaning it may change outside of the normal breaking change process. Consumers SHOULD use with caution. Default value is `false`. +experimental | `boolean` | Specifies that a schema is in experimental status, meaning it may change outside of the normal breaking change process. Consumers SHOULD use with caution. Default value is `false`. ### Example Spec @@ -89,7 +89,7 @@ Field Name | Type | Description required: true schema: type: string - beta: true + experimental: true ``` ### Prior Art @@ -100,16 +100,16 @@ This kind of requirement is handled for TypeScript libraries by [api-extractor]( ### Unanswered Questions -- If an operation is not marked as beta, but it is using a schema which is (i.e. as its request object), then it is implicitly also beta. Would this usage be considered invalid? -- Should `beta` and `deprecated` be mutually exclusive? +- If an operation is not marked as experimental, but it is using a schema which is (i.e. as its request object), then it is implicitly also unstable. Would this usage be considered invalid? +- Should `experimental` and `deprecated` be mutually exclusive? ## Backwards compatibility -The `beta` field would default to false, meaning existing behaviour is preserved, and the new field is only used on an opt-in basis. +The `experimental` field would default to false, meaning existing behaviour is preserved, and the new field is only used on an opt-in basis. ## Alternatives considered - _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 ill-advised. -- _Different API_ - this would be the least messy from a technical perspective - maintain a completely separate API for beta 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, beta items if they are segregated in a different place altogether. +- _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. From 584710e522042335de9bd5518b9abb935175a315 Mon Sep 17 00:00:00 2001 From: David Goss Date: Wed, 9 Dec 2020 20:28:06 +0000 Subject: [PATCH 10/16] mention stubs --- proposals/005_Experimental.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/005_Experimental.md b/proposals/005_Experimental.md index c6428991a1..20bfdc7ef3 100644 --- a/proposals/005_Experimental.md +++ b/proposals/005_Experimental.md @@ -38,7 +38,7 @@ _(I don't have a strong opinion about the naming - "beta" is another idea, thoug Downstream tools could then make use of this metadata: -- Tools like swagger-ui could surface this in the documentation they generate so consumers are made aware. Experimental items could also be filtered out of the documentation if desired. +- Tools like swagger-ui could surface this in the documentation they generate so consumers are made aware. Experimental items could also be filtered out of the documentation and stubs if desired. - Tools for detecting and preventing breaking changes could take this into consideration when deciding whether a change is breaking. ## Detailed design From 89518628dbf1c92c359aba6badee37df099901b9 Mon Sep 17 00:00:00 2001 From: David Goss Date: Wed, 9 Dec 2020 20:34:16 +0000 Subject: [PATCH 11/16] add to parameter --- proposals/005_Experimental.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/proposals/005_Experimental.md b/proposals/005_Experimental.md index 20bfdc7ef3..3822ec3ce1 100644 --- a/proposals/005_Experimental.md +++ b/proposals/005_Experimental.md @@ -46,9 +46,10 @@ Downstream tools could then make use of this metadata: A new boolean field named `experimental`, defaulting to `experimental`, is added to: - Operation +- Parameter - Schema -This specifies that the operation or schema is not yet stable and SHOULD be used with caution. +This specifies that the operation, parameter or schema is not yet stable and SHOULD be used with caution. ### Operation Object @@ -61,6 +62,17 @@ Field Name | Type | Description ... | ... | ... experimental | `boolean` | Specifies that an operation is in experimental status, meaning it may change outside of the normal breaking change process. Consumers SHOULD use with caution. Default value is `false`. +### Parameter Object + +... + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +... | ... | ... +experimental | `boolean` | Specifies that a parameter is in experimental status, meaning it may change outside of the normal breaking change process. Consumers SHOULD use with caution. Default value is `false`. Cannot be `true` when value of `in` is `path`. + ### Schema Object ... From d636c86f6aa127ee22a0e41df1f9961dac15dba0 Mon Sep 17 00:00:00 2001 From: David Goss Date: Wed, 9 Dec 2020 20:50:27 +0000 Subject: [PATCH 12/16] recast as being about `required` --- proposals/005_Experimental.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/005_Experimental.md b/proposals/005_Experimental.md index 3822ec3ce1..1a7067e8f9 100644 --- a/proposals/005_Experimental.md +++ b/proposals/005_Experimental.md @@ -71,7 +71,7 @@ Field Name | Type | Description Field Name | Type | Description ---|:---:|--- ... | ... | ... -experimental | `boolean` | Specifies that a parameter is in experimental status, meaning it may change outside of the normal breaking change process. Consumers SHOULD use with caution. Default value is `false`. Cannot be `true` when value of `in` is `path`. +experimental | `boolean` | Specifies that a parameter is in experimental status, meaning it may change outside of the normal breaking change process. Consumers SHOULD use with caution. Default value is `false`. Cannot be `true` when the parameter is `required`. ### Schema Object From f825f3f749c88339f39ed30bdddcad145413bfbe Mon Sep 17 00:00:00 2001 From: David Goss Date: Wed, 9 Dec 2020 21:02:33 +0000 Subject: [PATCH 13/16] discuss overlays as an alternative --- proposals/005_Experimental.md | 1 + 1 file changed, 1 insertion(+) diff --git a/proposals/005_Experimental.md b/proposals/005_Experimental.md index 1a7067e8f9..d4dfdaa9d6 100644 --- a/proposals/005_Experimental.md +++ b/proposals/005_Experimental.md @@ -123,5 +123,6 @@ The `experimental` field would default to false, meaning existing behaviour is p - _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. +- _Overlays_ - The [Overlays proposal](https://github.com/OAI/OpenAPI-Specification/blob/master/proposals/004_Overlays.md) is sufficiently powerful to be able to implement this, with a canonical spec representing the stable API and an overlay used to apply experimental additions. Downsides: not as ergonomic for authors, the OpenAPI specification would still not have "experimental" as a first-class concept so there'd be reliance on conventions being observed across the ecosystem for how it's done with overlays. - _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. From 4587338af6d3009a07662cb100c293c33a1345c5 Mon Sep 17 00:00:00 2001 From: David Goss Date: Thu, 17 Jun 2021 11:39:10 +0100 Subject: [PATCH 14/16] Update and rename 005_Experimental.md to 2020-10-28-Experimental.md --- proposals/{005_Experimental.md => 2020-10-28-Experimental.md} | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) rename proposals/{005_Experimental.md => 2020-10-28-Experimental.md} (91%) diff --git a/proposals/005_Experimental.md b/proposals/2020-10-28-Experimental.md similarity index 91% rename from proposals/005_Experimental.md rename to proposals/2020-10-28-Experimental.md index d4dfdaa9d6..4e289c958d 100644 --- a/proposals/005_Experimental.md +++ b/proposals/2020-10-28-Experimental.md @@ -4,7 +4,7 @@ |Tag |Value | |---- | ---------------- | -|Proposal |[005_Experimental](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/005_Experimental.md)| +|Proposal |[Experimental](https://github.com/OAI/OpenAPI-Specification/blob/main/proposals/2020-10-28-Experimental.md)| |Authors|[David Goss](https://github.com/davidjgoss)| |Review Manager |TBD | |Status |Proposal| @@ -123,6 +123,6 @@ The `experimental` field would default to false, meaning existing behaviour is p - _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. -- _Overlays_ - The [Overlays proposal](https://github.com/OAI/OpenAPI-Specification/blob/master/proposals/004_Overlays.md) is sufficiently powerful to be able to implement this, with a canonical spec representing the stable API and an overlay used to apply experimental additions. Downsides: not as ergonomic for authors, the OpenAPI specification would still not have "experimental" as a first-class concept so there'd be reliance on conventions being observed across the ecosystem for how it's done with overlays. +- _Overlays_ - The [Overlays proposal](https://github.com/OAI/OpenAPI-Specification/blob/main/proposals/2019-12-24-Overlays.md) is sufficiently powerful to be able to implement this, with a canonical spec representing the stable API and an overlay used to apply experimental additions. Downsides: not as ergonomic for authors, the OpenAPI specification would still not have "experimental" as a first-class concept so there'd be reliance on conventions being observed across the ecosystem for how it's done with overlays. - _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. From 7ce2ecf0d6dd4c5af009b9806f987eb458bf04c6 Mon Sep 17 00:00:00 2001 From: David Goss Date: Sun, 14 Apr 2024 17:25:52 +0100 Subject: [PATCH 15/16] express default value as boolean Co-authored-by: Ralf Handl --- proposals/2020-10-28-Experimental.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2020-10-28-Experimental.md b/proposals/2020-10-28-Experimental.md index 4e289c958d..17693dbd51 100644 --- a/proposals/2020-10-28-Experimental.md +++ b/proposals/2020-10-28-Experimental.md @@ -43,7 +43,7 @@ Downstream tools could then make use of this metadata: ## Detailed design -A new boolean field named `experimental`, defaulting to `experimental`, is added to: +A new boolean field named `experimental`, defaulting to `false`, is added to: - Operation - Parameter From 4f42b069bedeb518873731a4f330a8d6760a50e6 Mon Sep 17 00:00:00 2001 From: David Goss Date: Mon, 15 Apr 2024 14:15:54 +0100 Subject: [PATCH 16/16] clarify relationship with deprecated --- proposals/2020-10-28-Experimental.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/proposals/2020-10-28-Experimental.md b/proposals/2020-10-28-Experimental.md index 17693dbd51..aa34522070 100644 --- a/proposals/2020-10-28-Experimental.md +++ b/proposals/2020-10-28-Experimental.md @@ -113,12 +113,13 @@ This kind of requirement is handled for TypeScript libraries by [api-extractor]( ### Unanswered Questions - If an operation is not marked as experimental, but it is using a schema which is (i.e. as its request object), then it is implicitly also unstable. Would this usage be considered invalid? -- Should `experimental` and `deprecated` be mutually exclusive? ## Backwards compatibility The `experimental` field would default to false, meaning existing behaviour is preserved, and the new field is only used on an opt-in basis. +`experimental` can coexist with `deprecated` - an operation, parameter or schema can be both experimental and deprecated, having never gotten to a stable point before being deprecated. + ## Alternatives considered - _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.