diff --git a/output/schema/schema.json b/output/schema/schema.json
index 281a5e3bec..91a1cdb5eb 100644
--- a/output/schema/schema.json
+++ b/output/schema/schema.json
@@ -39815,7 +39815,7 @@
         "name": "AggregateOrder",
         "namespace": "_types.aggregations"
       },
-      "specLocation": "_types/aggregations/bucket.ts#L395-L397",
+      "specLocation": "_types/aggregations/bucket.ts#L399-L401",
       "type": {
         "items": [
           {
@@ -42055,7 +42055,7 @@
           }
         }
       ],
-      "specLocation": "_types/aggregations/bucket.ts#L429-L493"
+      "specLocation": "_types/aggregations/bucket.ts#L433-L497"
     },
     {
       "codegenNames": [
@@ -42067,7 +42067,7 @@
         "name": "CategorizeTextAnalyzer",
         "namespace": "_types.aggregations"
       },
-      "specLocation": "_types/aggregations/bucket.ts#L495-L498",
+      "specLocation": "_types/aggregations/bucket.ts#L499-L502",
       "type": {
         "items": [
           {
@@ -42511,7 +42511,7 @@
           }
         }
       ],
-      "specLocation": "_types/aggregations/bucket.ts#L500-L504"
+      "specLocation": "_types/aggregations/bucket.ts#L504-L508"
     },
     {
       "inherits": {
@@ -49766,7 +49766,7 @@
         "name": "TermsAggregationCollectMode",
         "namespace": "_types.aggregations"
       },
-      "specLocation": "_types/aggregations/bucket.ts#L399-L402"
+      "specLocation": "_types/aggregations/bucket.ts#L403-L406"
     },
     {
       "kind": "enum",
@@ -49788,7 +49788,7 @@
         "name": "TermsAggregationExecutionHint",
         "namespace": "_types.aggregations"
       },
-      "specLocation": "_types/aggregations/bucket.ts#L404-L409"
+      "specLocation": "_types/aggregations/bucket.ts#L408-L413"
     },
     {
       "attachedBehaviors": [
@@ -49830,7 +49830,7 @@
         "name": "TermsExclude",
         "namespace": "_types.aggregations"
       },
-      "specLocation": "_types/aggregations/bucket.ts#L414-L415",
+      "specLocation": "_types/aggregations/bucket.ts#L418-L419",
       "type": {
         "items": [
           {
@@ -49865,7 +49865,7 @@
         "name": "TermsInclude",
         "namespace": "_types.aggregations"
       },
-      "specLocation": "_types/aggregations/bucket.ts#L411-L412",
+      "specLocation": "_types/aggregations/bucket.ts#L415-L416",
       "type": {
         "items": [
           {
@@ -49926,7 +49926,7 @@
           }
         }
       ],
-      "specLocation": "_types/aggregations/bucket.ts#L417-L420"
+      "specLocation": "_types/aggregations/bucket.ts#L421-L424"
     },
     {
       "kind": "interface",
@@ -50595,7 +50595,7 @@
           }
         }
       ],
-      "specLocation": "_types/aggregations/bucket.ts#L422-L427"
+      "specLocation": "_types/aggregations/bucket.ts#L426-L431"
     },
     {
       "attachedBehaviors": [
diff --git a/specification/_types/aggregations/bucket.ts b/specification/_types/aggregations/bucket.ts
index b408ecc09d..f20384a8e9 100644
--- a/specification/_types/aggregations/bucket.ts
+++ b/specification/_types/aggregations/bucket.ts
@@ -392,6 +392,10 @@ export class TermsAggregation extends BucketAggregationBase {
   format?: string
 }
 
+// Note: ES is very lazy when parsing this data type: it accepts any number of properties in the objects below,
+// but will only keep the *last* property in JSON document order and ignore others.
+// This means that something like `"order": { "downloads": "desc", "_key": "asc" }` will actually be interpreted
+// as `"order": [ { "_key": "asc" } ]`
 export type AggregateOrder =
   | SingleKeyDictionary<Field, SortOrder>
   | SingleKeyDictionary<Field, SortOrder>[]