diff -u b/core/lib/Drupal/Core/Database/database.api.php b/core/lib/Drupal/Core/Database/database.api.php
--- b/core/lib/Drupal/Core/Database/database.api.php
+++ b/core/lib/Drupal/Core/Database/database.api.php
@@ -256,7 +256,7 @@
  *     - 'description': A string in non-markup plain text describing this field
  *       and its purpose. References to other tables should be enclosed in
  *       curly-brackets. For example, the users_data table uid field
- *       description might contain "Primary key: {users}.uid for user."
+ *       description might contain "The {users}.uid this record affects."
  *     - 'type': The generic datatype: 'char', 'varchar', 'text', 'blob', 'int',
  *       'float', 'numeric', or 'serial'. Most types just map to the according
  *       database engine specific data types. Use 'serial' for auto incrementing
@@ -323,18 +323,17 @@
  * array of two elements, column name and length, specifying a prefix
  * of the named column.
  *
- * As an example, here is a SUBSET of the schema definition for
- * Drupal's 'users_data' table. It show four fields (uid, module, name, value,
- * and serialized), the primary key on fields ('uid', 'module', and 'name'),
- * two indexes, one named 'module' on field 'module' and one named 'name' on
- * the field 'name':
+ * As an example, this is the schema definition for the Drupal's users_data
+ * table. It shows four fields (uid, module, name, value, and serialized),
+ * the primary key (on the uid, module, and name fields), and two indexes (one
+ * named module on the module field, and one named name on the name field).
  *
  * @code
  * $schema['users_data'] = [
  *   'description' => 'Stores module data as key/value pairs per user.',
  *   'fields' => [
  *     'uid' => [
- *       'description' => 'Primary key: {users}.uid for user.',
+ *       'description' => 'The {users}.uid this record affects.',
  *       'type' => 'int',
  *       'unsigned' => TRUE,
  *       'not null' => TRUE,
@@ -376,8 +375,13 @@
  *   // For documentation purposes only; foreign keys are not created in the
  *   // database.
  *   'foreign keys' => [
- *     'uid' => ['users' => 'uid'],
- *   ],
+ *     'data_user' => [
+ *      'table' => 'users',
+ *      'columns' => [
+ *        'uid' => 'uid',
+ *      ],
+ *    ],
+ *  ],
  * ];
  * @endcode
  *
@@ -493,7 +497,7 @@
     'description' => 'Stores module data as key/value pairs per user.',
     'fields' => [
       'uid' => [
-        'description' => 'Primary key: {users}.uid for user.',
+        'description' => 'The {users}.uid this record affects.',
         'type' => 'int',
         'unsigned' => TRUE,
         'not null' => TRUE,
@@ -535,7 +539,12 @@
     // For documentation purposes only; foreign keys are not created in the
     // database.
     'foreign keys' => [
-      'uid' => ['users' => 'uid'],
+      'data_user' => [
+        'table' => 'users',
+        'columns' => [
+          'uid' => 'uid',
+        ],
+      ],
     ],
   ];