diff --git a/openapi_extensions.md b/openapi_extensions.md
index e8fd1002a..017aaf7d4 100644
--- a/openapi_extensions.md
+++ b/openapi_extensions.md
@@ -41,3 +41,8 @@ same use as `format`, but that applies to the pattern of the property. We also
 define custom values for formats with the `mx-` prefix in
 `data/custom-formats.yaml`. Those values are recognized in the rendered
 specification and link to the definition of the format.
+
+## Custom `x-weight` key
+
+This property allows controlling the display order of events rendered with the
+`event-group` shortcode.