diff --git a/jsonapi.api.php b/jsonapi.api.php
index 8c63bfc..b57c188 100644
--- a/jsonapi.api.php
+++ b/jsonapi.api.php
@@ -75,6 +75,16 @@
  * The JSON API module exposes entity revisions in a manner inspired by RFC5829:
  * Link Relation Types for Simple Version Navigation between Web Resources.
  *
+ * Revision support is not an official part of the JSON API specification.
+ * However, a number of "profiles" are being developed (also not officially part
+ * in the spec, but already committed to JSON API v1.1) to standardize any
+ * custom behaviors that the JSON API module has developed (all of which are
+ * still specification compliant).
+ *
+ * @see https://github.com/json-api/json-api/pull/1268
+ * @see https://github.com/json-api/json-api/pull/1311
+ * @see https://www.drupal.org/project/jsonapi/issues/2955020
+ *
  * In doing so, JSON API module should be maximally compatible with other
  * systems and should minimize the "Drupalisms" that a developer building
  * against a JSON API implementation will be required to know.
@@ -129,6 +139,9 @@
  * @code /jsonapi/node/page/{{uuid}}?resource_version=id:{{revision_id}}
  * @endcode.
  *
+ * It is not yet possible to request a collection of revisions. This is under
+ * development here: @link https://www.drupal.org/project/jsonapi/issues/3009588.
+ *
  * @see https://tools.ietf.org/html/rfc5829
  *
  *