diff --git a/api-ref/source/os-security-group-rules.inc b/api-ref/source/os-security-group-rules.inc
index 00468c11360e..896fb68cfbf3 100644
--- a/api-ref/source/os-security-group-rules.inc
+++ b/api-ref/source/os-security-group-rules.inc
@@ -1,5 +1,4 @@
 .. -*- rst -*-
-.. needs:parameter_verification
 .. needs:example_verification
 .. needs:body_verification
 
@@ -14,7 +13,8 @@ Create Security Group Rule
 
 .. rest_method:: POST /v2.1/{tenant_id}/os-security-group-rules
 
-Creates a rule for a security group.
+Creates a rule for a security group. Either ``cidr`` or ``group_id`` must be
+specified when creating a rule.
 
 Normal response codes: 200
 
@@ -31,7 +31,7 @@ Request
   - ip_protocol: ip_protocol
   - from_port: from_port
   - to_port: to_port
-  - cidr: cidr
+  - cidr: secgroup_rule_cidr
   - group_id: group_id
 
 .. TODO(sdague): we currently have no samples here
@@ -43,18 +43,23 @@ Request
 Response
 --------
 
+The ``group`` is empty if ``group_id`` was not provided on the request.
+
+The ``ip_range`` is empty if ``cidr`` was not provided on the request.
+
 .. rest_parameters:: parameters.yaml
 
   - security_group_rule: security_group_rule
   - ip_protocol: ip_protocol
   - from_port: from_port
   - to_port: to_port
-  - ip_range: ip_range
-  - cidr: cidr
-  - id: id
+  - ip_range: secgroup_rule_ip_range
+  - cidr: secgroup_rule_cidr
+  - id: secgroup_rule_id
   - group: group
   - parent_group_id: parent_group_id
   - name: name
+  - tenant_id: secgroup_tenant_id_body
 
 .. TODO(sdague): we currently have no samples here
    **Example Create security group rule: JSON response**
diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml
index 1804e25cc05b..6e2c9fab3ec1 100644
--- a/api-ref/source/parameters.yaml
+++ b/api-ref/source/parameters.yaml
@@ -1110,18 +1110,13 @@ from_port:
   in: body
   required: true
   type: integer
-from_port_1:
-  description: |
-    Port at start of range.
-  in: body
-  required: true
-  type: integer
 group:
   description: |
-    A ``group`` object. Includes the tenant ID and the source security group name.
+    A ``group`` object. Includes the ``tenant_id`` and the source security
+    group ``name``.
   in: body
   required: true
-  type: string
+  type: object
 group_id:
   description: |
     The source security group ID.
@@ -1329,30 +1324,13 @@ ip_protocol:
   in: body
   required: true
   type: string
-ip_protocol_1:
-  description: |
-    The IP protocol: ICMP, TCP, or UDP.
-  in: body
-  required: true
-  type: string
 ip_range:
   description: |
     The range of IP addresses to use for creating floating IPs.
   in: body
   required: true
   type: string
-ip_range_1:
-  description: |
-    An IP range object.
-  in: body
-  required: true
-  type: string
-ip_range_2:
-  description: |
-    An ``ip_range`` object.
-  in: body
-  required: true
-  type: string
+# TODO(mriedem): this needs to be renamed and used in os-floating-ips-bulk.inc
 ip_range_3:
   description: |
     The range of IP addresses from which to bulk-delete floating IPs.
@@ -1926,6 +1904,30 @@ rules_1:
   in: body
   required: true
   type: string
+secgroup_rule_cidr:
+  description: |
+    The CIDR for address range.
+  in: body
+  required: false
+  type: string
+secgroup_rule_id:
+  description: |
+    The security group rule ID.
+  in: body
+  required: true
+  type: string
+secgroup_rule_ip_range:
+  description: |
+    An IP range object. Includes the security group rule ``cidr``.
+  in: body
+  required: true
+  type: object
+secgroup_tenant_id_body:
+  description: |
+    The UUID of the tenant that owns this security group.
+  in: body
+  required: true
+  type: string
 security_group:
   description: |
     Specify the ``security_group`` action in the request body.
@@ -2130,12 +2132,6 @@ to_port:
   in: body
   required: true
   type: integer
-to_port_1:
-  description: |
-    Port at end of range.
-  in: body
-  required: true
-  type: integer
 type:
   description: |
     The snapshot type. A valid value is ``qcow2``.