Skip to content

Commit ca9abf6

Browse files
lornajanelornajane
authored
Merge pull request #2386 from davidjgoss/proposal-beta
Draft proposal for experimental field
2 parents 8a8a9a6 + 4f42b06 commit ca9abf6

File tree

1 file changed

+129
-0
lines changed

1 file changed

+129
-0
lines changed

‎proposals/2020-10-28-Experimental.md

+129
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
# Experimental marker
2+
3+
## Metadata
4+
5+
|Tag |Value |
6+
|---- | ---------------- |
7+
|Proposal |[Experimental](https://github.com/OAI/OpenAPI-Specification/blob/main/proposals/2020-10-28-Experimental.md)|
8+
|Authors|[David Goss](https://github.com/davidjgoss)|
9+
|Review Manager |TBD |
10+
|Status |Proposal|
11+
|Implementations ||
12+
|Issues ||
13+
|Previous Revisions ||
14+
15+
## Change Log
16+
17+
|Date |Responsible Party |Description |
18+
|---- | ---------------- | ---------- |
19+
20+
## Introduction
21+
22+
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.
23+
24+
## Motivation
25+
26+
Consider an API with two categories of thing in it:
27+
28+
- Core, stable things, where we are committed to the ongoing stability and have no intention of making breaking changes.
29+
- 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.
30+
31+
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.
32+
33+
## Proposed solution
34+
35+
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.
36+
37+
_(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.)_
38+
39+
Downstream tools could then make use of this metadata:
40+
41+
- 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.
42+
- Tools for detecting and preventing breaking changes could take this into consideration when deciding whether a change is breaking.
43+
44+
## Detailed design
45+
46+
A new boolean field named `experimental`, defaulting to `false`, is added to:
47+
48+
- Operation
49+
- Parameter
50+
- Schema
51+
52+
This specifies that the operation, parameter or schema is not yet stable and SHOULD be used with caution.
53+
54+
### Operation Object
55+
56+
...
57+
58+
##### Fixed Fields
59+
60+
Field Name | Type | Description
61+
---|:---:|---
62+
... | ... | ...
63+
<a name="operationExperimental"></a>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`.
64+
65+
### Parameter Object
66+
67+
...
68+
69+
##### Fixed Fields
70+
71+
Field Name | Type | Description
72+
---|:---:|---
73+
... | ... | ...
74+
<a name="parameterExperimental"></a>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`.
75+
76+
### Schema Object
77+
78+
...
79+
80+
##### Fixed Fields
81+
82+
Field Name | Type | Description
83+
---|:---:|---
84+
... | ... | ...
85+
<a name="schemaExperimental"></a>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`.
86+
87+
### Example Spec
88+
89+
```yaml
90+
/asset/constraints:
91+
get:
92+
tags:
93+
- Asset
94+
- Constraints
95+
summary: Get a set of asset constraints
96+
operationId: constraints
97+
parameters:
98+
- name: siteToken
99+
in: query
100+
description: Site token obtained from Site API
101+
required: true
102+
schema:
103+
type: string
104+
experimental: true
105+
```
106+
### Prior Art
107+
108+
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:
109+
110+
> - **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.
111+
> - **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.
112+
113+
### Unanswered Questions
114+
115+
- 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?
116+
117+
## Backwards compatibility
118+
119+
The `experimental` field would default to false, meaning existing behaviour is preserved, and the new field is only used on an opt-in basis.
120+
121+
`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.
122+
123+
## Alternatives considered
124+
125+
- _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.
126+
- _Tags_ - as above, but this also gets to mixing other kinds of metadata in with resource taxonomy, which seems wrong.
127+
- _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.
128+
- _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.
129+

0 commit comments

Comments
 (0)