added beta feature designation and description

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](#betafeatures)
 
 ## 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 newly established endpoints or fields. Because beta features are new, they may not 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 also likely new as well and are more likely to contain bugs or other problems. Beta features are likely to evolve more rapidly than other parts of the specification.
+
+Despite this, MDS users are encouraged to use beta features. New features can only become proven and trusted through use and the learning that comes with it. Users should be thoughtful about the role of beta features in their operations. Beta features are suitable for enabling new tools and analysis, but may not be appropriate for mission-critical 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 help the  community make the improvements that allow beta features to become 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