diff --git a/specification/resources/databases/databases_create_cluster.yml b/specification/resources/databases/databases_create_cluster.yml
index e4d9a1ac5..98e82d03f 100644
--- a/specification/resources/databases/databases_create_cluster.yml
+++ b/specification/resources/databases/databases_create_cluster.yml
@@ -80,6 +80,7 @@ requestBody:
                 value: "163973392"
               - type: tag
                 value: test
+                description: "a test tag"
 
         Restore from a Database Cluster Backup:
           value:
diff --git a/specification/resources/databases/databases_update_firewall_rules.yml b/specification/resources/databases/databases_update_firewall_rules.yml
index 6b6125fe5..ea49be267 100644
--- a/specification/resources/databases/databases_update_firewall_rules.yml
+++ b/specification/resources/databases/databases_update_firewall_rules.yml
@@ -41,6 +41,7 @@ requestBody:
           value: '163973392'
         - type: tag
           value: backend
+          description: 'a backend tag'
 
 parameters:
   - $ref: 'parameters.yml#/database_cluster_uuid'
diff --git a/specification/resources/databases/examples/go/databases_update_firewall_rules.yml b/specification/resources/databases/examples/go/databases_update_firewall_rules.yml
index 5ae60d2c7..5573112d8 100644
--- a/specification/resources/databases/examples/go/databases_update_firewall_rules.yml
+++ b/specification/resources/databases/examples/go/databases_update_firewall_rules.yml
@@ -18,6 +18,7 @@ source: |-
           {
            Type:  "ip_addr",
            Value: "192.168.1.1",
+           Description: "a development IP address",
          },
           {
            Type:  "droplet",
diff --git a/specification/resources/databases/examples/python/databases_update_firewall_rules.yml b/specification/resources/databases/examples/python/databases_update_firewall_rules.yml
index cfc6af1e0..4c234d5e8 100644
--- a/specification/resources/databases/examples/python/databases_update_firewall_rules.yml
+++ b/specification/resources/databases/examples/python/databases_update_firewall_rules.yml
@@ -9,7 +9,8 @@ source: |-
     "rules": [
       {
         "type": "ip_addr",
-        "value": "192.168.1.1"
+        "value": "192.168.1.1",
+        "description": "a development IP address",
       },
       {
         "type": "k8s",
diff --git a/specification/resources/databases/models/firewall_rule.yml b/specification/resources/databases/models/firewall_rule.yml
index d93e723d9..93bf94ee9 100644
--- a/specification/resources/databases/models/firewall_rule.yml
+++ b/specification/resources/databases/models/firewall_rule.yml
@@ -39,7 +39,11 @@ properties:
       A time value given in ISO8601 combined date and time format that
       represents when the firewall rule was created.
     readOnly: true
-
+  description:
+      type: string
+      example: 'an IP address for local development'
+      description: >-
+        A human-readable description of the rule.
 required:
   - type
   - value
diff --git a/specification/resources/databases/responses/firewall_rules.yml b/specification/resources/databases/responses/firewall_rules.yml
index a6367d2e2..075190557 100644
--- a/specification/resources/databases/responses/firewall_rules.yml
+++ b/specification/resources/databases/responses/firewall_rules.yml
@@ -26,6 +26,7 @@ content:
       - uuid: adfe81a8-0fa1-4e2d-973f-06aa5af19b44
         cluster_uuid: 9cc10173-e9ea-4176-9dbc-a4cee4c4ff30
         type: ip_addr
+        description: 'a development IP address'
         value: 192.168.1.1
         created_at: '2019-11-14T20:30:28Z'
       - uuid: b9b42276-8295-4313-b40f-74173a7f46e6