diff --git a/api-ref/source/os-aggregates.inc b/api-ref/source/os-aggregates.inc
index ecfefe59ac60..a8ff9df9c96b 100644
--- a/api-ref/source/os-aggregates.inc
+++ b/api-ref/source/os-aggregates.inc
@@ -31,7 +31,7 @@ Response
   - deleted: deleted
   - hosts: aggregate_host_list
   - id: aggregate_id_body
-  - metadata: aggregate_metadata
+  - metadata: aggregate_metadata_response
   - name: aggregate_name
   - updated_at: updated_consider_null
   - uuid: aggregate_uuid
@@ -60,7 +60,7 @@ Request
 
   - aggregate: aggregate
   - name: aggregate_name
-  - availability_zone: aggregate_az_optional
+  - availability_zone: aggregate_az_optional_create
 
 **Example Create Aggregate: JSON request**
 
@@ -117,7 +117,7 @@ Response
   - deleted: deleted
   - hosts: hosts
   - id: aggregate_id_body
-  - metadata: aggregate_metadata
+  - metadata: aggregate_metadata_response
   - name: aggregate_name
   - updated_at: updated_consider_null
   - uuid: aggregate_uuid
@@ -149,7 +149,7 @@ Request
   - aggregate_id: aggregate_id
   - aggregate: aggregate
   - name: aggregate_name_optional
-  - availability_zone: aggregate_az_optional
+  - availability_zone: aggregate_az_optional_update
 
 **Example Update Aggregate: JSON request**
 
@@ -168,7 +168,7 @@ Response
   - deleted: deleted
   - hosts: hosts
   - id: aggregate_id_body
-  - metadata: aggregate_metadata
+  - metadata: aggregate_metadata_response
   - name: aggregate_name
   - updated_at: updated_consider_null
   - uuid: aggregate_uuid
@@ -241,7 +241,7 @@ Response
   - deleted: deleted
   - hosts: hosts
   - id: aggregate_id_body
-  - metadata: aggregate_metadata
+  - metadata: aggregate_metadata_response
   - name: aggregate_name
   - updated_at: updated_consider_null
   - uuid: aggregate_uuid
@@ -291,7 +291,7 @@ Response
   - deleted: deleted
   - hosts: hosts
   - id: aggregate_id_body
-  - metadata: aggregate_metadata
+  - metadata: aggregate_metadata_response
   - name: aggregate_name
   - updated_at: updated_consider_null
   - uuid: aggregate_uuid
@@ -322,7 +322,7 @@ Request
 
   - aggregate_id: aggregate_id
   - set_metadata: set_metadata
-  - metadata: metadata_object 
+  - metadata: aggregate_metadata_request
 
 **Example Create Or Update Aggregate Metadata: JSON request**
 
@@ -341,7 +341,7 @@ Response
   - deleted: deleted
   - hosts: hosts
   - id: aggregate_id_body
-  - metadata: aggregate_metadata
+  - metadata: aggregate_metadata_response
   - name: aggregate_name
   - updated_at: updated_consider_null
   - uuid: aggregate_uuid
diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml
index ed6ce9bac27b..258d7f7a31ad 100644
--- a/api-ref/source/parameters.yaml
+++ b/api-ref/source/parameters.yaml
@@ -1604,7 +1604,7 @@ aggregate_az:
   in: body
   required: true
   type: string
-aggregate_az_optional:
+aggregate_az_optional_create:
   description: |
     The availability zone of the host aggregate. You should use a custom
     availability zone rather than the default returned by the
@@ -1613,6 +1613,20 @@ aggregate_az_optional:
   in: body
   required: false
   type: string
+aggregate_az_optional_update:
+  description: |
+    The availability zone of the host aggregate. You should use a custom
+    availability zone rather than the default returned by the
+    os-availability-zone API. The availability zone must not include ':'
+    in its name.
+
+    .. warning:: You should not change or unset the availability zone of an
+      aggregate when that aggregate has hosts which contain servers in it
+      since that may impact the ability for those servers to move to another
+      host.
+  in: body
+  required: false
+  type: string
 aggregate_host_list:
   description: |
     A list of host ids in this aggregate.
@@ -1625,9 +1639,21 @@ aggregate_id_body:
   in: body
   required: true
   type: integer
-aggregate_metadata:
+aggregate_metadata_request:
   description: |
-    Metadata key and value pairs associate with the aggregate.
+    Metadata key and value pairs associated with the aggregate.
+    The maximum size for each metadata key and value pair is 255 bytes.
+
+    .. warning:: You should not change or unset the availability zone of an
+      aggregate when that aggregate has hosts which contain servers in it
+      since that may impact the ability for those servers to move to another
+      host.
+  in: body
+  required: true
+  type: object
+aggregate_metadata_response:
+  description: |
+    Metadata key and value pairs associated with the aggregate.
   in: body
   required: true
   type: object