diff --git a/jOOQ/src/main/java/org/jooq/JSON.java b/jOOQ/src/main/java/org/jooq/JSON.java
index dae1a34fe8..6344034631 100644
--- a/jOOQ/src/main/java/org/jooq/JSON.java
+++ b/jOOQ/src/main/java/org/jooq/JSON.java
@@ -39,6 +39,12 @@ package org.jooq;
 
 /**
  * A JSON wrapper type for JSON data obtained from the database.
+ * <p>
+ * The wrapper represents JSON {@link #data()} in serialised string form. A
+ * <code>CAST(NULL AS JSON)</code> value is represented by a <code>null</code>
+ * reference of type {@link JSON}, not as <code>data() == null</code>. This is
+ * consistent with jOOQ's general way of returning <code>NULL</code> from
+ * {@link Result} and {@link Record} methods.
  */
 public final class JSON {
 
diff --git a/jOOQ/src/main/java/org/jooq/JSONB.java b/jOOQ/src/main/java/org/jooq/JSONB.java
index 9d12488b00..9d8fd93474 100644
--- a/jOOQ/src/main/java/org/jooq/JSONB.java
+++ b/jOOQ/src/main/java/org/jooq/JSONB.java
@@ -39,6 +39,12 @@ package org.jooq;
 
 /**
  * A JSON wrapper type for JSONB data obtained from the database.
+ * <p>
+ * The wrapper represents JSONB {@link #data()} in serialised string form. A
+ * <code>CAST(NULL AS JSONB)</code> value is represented by a <code>null</code>
+ * reference of type {@link JSONB}, not as <code>data() == null</code>. This is
+ * consistent with jOOQ's general way of returning <code>NULL</code> from
+ * {@link Result} and {@link Record} methods.
  */
 public final class JSONB {