diff --git a/api/src/main/java/jakarta/persistence/Basic.java b/api/src/main/java/jakarta/persistence/Basic.java
index 3971cd78..8f2ddc30 100644
--- a/api/src/main/java/jakarta/persistence/Basic.java
+++ b/api/src/main/java/jakarta/persistence/Basic.java
@@ -65,6 +65,13 @@
  * protected String getName() { return name; }
  * }
  *
+ * <p>The use of {@link java.util.Date}, {@link java.util.Calendar},
+ * {@code java.sql.Date}, {@code java.sql.Time}, {@code java.sql.Timestamp},
+ * {@code Character[]}, or {@code Byte[]} as the type of a basic attribute
+ * is now discouraged. Newly-written code should use the date/time types
+ * defined in the package {@code java.time}, or the primitive array types
+ * {@code char[]} and {@code byte[]}.
+ *
  * @since 1.0
  */
 @Target({METHOD, FIELD}) 
diff --git a/spec/src/main/asciidoc/ch02-entities.adoc b/spec/src/main/asciidoc/ch02-entities.adoc
index 0fb078ce..ebeabc79 100644
--- a/spec/src/main/asciidoc/ch02-entities.adoc
+++ b/spec/src/main/asciidoc/ch02-entities.adoc
@@ -181,8 +181,10 @@ fully initialized for the type that it is mapped to.]
 of `java.util.Calendar` or of `java.util.Date` and its subclasses in the
 package `java.sql` is strongly discouraged. Newly-written programs should
 use date/time types from the package `java.time`.]
-`byte[]`, `Byte[]`, `char[]`, `Character[]`, `java.time.LocalDate`,
-`java.time.LocalTime`, `java.time.LocalDateTime`,
+`byte[]`, `Byte[]`, `char[]`, `Character[]`,footnote:[The use of `Byte[]`
+or of `Character[]` is discouraged. Newly-written programs should use
+`byte[]` or `char[]` instead.]
+`java.time.LocalDate`, `java.time.LocalTime`, `java.time.LocalDateTime`,
 `java.time.OffsetTime`, `java.time.OffsetDateTime`,
 `java.time.Instant`, `java.time.Year`,
 and user-defined types that implement the `Serializable` interface);