Define "beta" features and replace the optional/required designation for endpoints (#468)

Author: jfh01

general-information.md

@@ -5,6 +5,7 @@ This document contains specifications that are shared between the various MDS AP
 ## Table of Contents
 
 * [Versioning](#versioning)
+* [Beta Features](#beta-features)
 
 ## Versioning
 
@@ -45,4 +46,11 @@ Content-Type: application/vnd.mds.provider+json;version=0.3
 
 The client can use the returned value verbatim as a version request in the `Accept` header.
 
+## Beta Features
+In some cases, features within MDS may be marked as "beta." These are typically recently added endpoints or fields. Because beta features are new, they may not yet be fully mature and proven in real-world operation. The design of beta features may have undiscovered gaps, ambiguities, or inconsistencies. Implementations of those features are typically also quite new and are more likely to contain bugs or other flaws. Beta features are likely to evolve more rapidly than other parts of the specification.
+
+Despite this, MDS users are highly encouraged to use beta features. New features can only become proven and trusted through implementation, use, and the learning that comes with it. Users should be thoughtful about the role of beta features in their operations. Beta features may be suitable for enabling some new tools and analysis, but may not be appropriate for mission-critical applications or regulatory decisions where certainty and reliability are essential.
+
+Users of beta features are strongly encouraged to share their experiences, learnings, and challenges with the broader MDS community via GitHub issues or pull requests. This will inform the refinements that transform beta features into fully proven, stable parts of the specification.
+
 [Top](#table-of-contents)

provider/README.md

@@ -203,7 +203,7 @@ Unless stated otherwise by the municipality, the trips endpoint must return all
 
 **Endpoint:** `/trips`  
 **Method:** `GET`  
-**Required/Optional:** Required  
+**[Beta feature](/general-information.md#beta-features):** No  
 **Schema:** [`trips` schema][trips-schema]  
 **`data` Payload:** `{ "trips": [] }`, an array of objects with the following structure  
 
@@ -294,7 +294,7 @@ Unless stated otherwise by the municipality, this endpoint must return only thos
 
 **Endpoint:** `/status_changes`  
 **Method:** `GET`  
-**Required/Optional:** Required  
+**[Beta feature](/general-information.md#beta-features):** No  
 **Schema:** [`status_changes` schema][sc-schema]  
 **`data` Payload:** `{ "status_changes": [] }`, an array of objects with the following structure
 
@@ -375,7 +375,7 @@ The schema and datatypes are the same as those defined for [`/status_changes`][s
 
 **Endpoint:** `/events`  
 **Method:** `GET`  
-**Required/Optional:** Optional starting with `0.4.0`, moving to Required in a future version (`0.5.0`+)  
+**[Beta feature](/general-information.md#beta-features):** Yes (as of 0.4.0)  
 **Schema:** [`events` schema][events-schema]  
 **`data` Payload:** `{ "status_changes": [] }`, an array of objects with the same structure as in [`/status_changes`][status]
 
@@ -422,7 +422,7 @@ ttl                 | Yes       | Integer representing the number of millisecond
 
 **Endpoint:** `/vehicles`  
 **Method:** `GET`  
-**Required/Optional:** Optional starting with `0.4.1`, moving to Required in a future version (`0.5.0`+)  
+**[Beta feature](/general-information.md#beta-features):** Yes (as of 0.4.1)  
 **Schema:** [`vehicles` schema][vehicles-schema]  
 **`data` Payload:** `{ "vehicles": [] }`, an array of objects with the following structure
 
@@ -451,4 +451,4 @@ ttl                 | Yes       | Integer representing the number of millisecond
 [toc]: #table-of-contents
 [trips-schema]: dockless/trips.json
 [ts]: #timestamps
-[vehicles-schema]: dockless/vehicles.json
+[vehicles-schema]: dockless/vehicles.json