diff --git a/jOOQ/src/main/java/org/jooq/JSON.java b/jOOQ/src/main/java/org/jooq/JSON.java
index 40655a8db8..ec3a709735 100644
--- a/jOOQ/src/main/java/org/jooq/JSON.java
+++ b/jOOQ/src/main/java/org/jooq/JSON.java
@@ -50,6 +50,23 @@ import org.jetbrains.annotations.Nullable;
  * 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.
+ * <p>
+ * Unlike the normalising {@link JSONB} data type, the {@link JSON} type uses a
+ * purely text based, formatting-preserving representation of the JSON content,
+ * meaning that e.g. the following two documents are <em>not</em> equal, due to
+ * their different object attribute order and formatting:
+ * <p>
+ * <ul>
+ * <li><code>{"a":1,"b":2}</code></li>
+ * <li><code>{"b": 2, "a": 1}</code></li>
+ * </ul>
+ * <p>
+ * This impacts the behaviour of
+ * <ul>
+ * <li>{@link #equals(Object)}</li>
+ * <li>{@link #hashCode()}</li>
+ * <li>{@link #toString()}</li>
+ * </ul>
  */
 public final class JSON implements Serializable {
 
@@ -92,11 +109,31 @@ public final class JSON implements Serializable {
         return data == null ? null : json(data);
     }
 
+    /**
+     * {@inheritDoc}
+     * <p>
+     * <h3>{@link JSON} specifics:</h3>
+     * <p>
+     * The {@link JSON} type uses a text-based, formatting-preserving
+     * representation of the JSON content, meaning that two equivalent JSON
+     * documents are considered not equal if their formatting or object
+     * attribute ordering differs (see {@link JSON} for details).
+     */
     @Override
     public int hashCode() {
         return data.hashCode();
     }
 
+    /**
+     * {@inheritDoc}
+     * <p>
+     * <h3>{@link JSON} specifics:</h3>
+     * <p>
+     * The {@link JSON} type uses a text-based, formatting-preserving
+     * representation of the JSON content, meaning that two equivalent JSON
+     * documents are considered not equal if their formatting or object
+     * attribute ordering differs (see {@link JSON} for details).
+     */
     @Override
     public boolean equals(Object obj) {
         if (this == obj)
@@ -107,6 +144,16 @@ public final class JSON implements Serializable {
 
     }
 
+    /**
+     * {@inheritDoc}
+     * <p>
+     * <h3>{@link JSON} specifics:</h3>
+     * <p>
+     * The {@link JSON} type uses a text-based, formatting-preserving
+     * representation of the JSON content, meaning that two equivalent JSON
+     * documents are considered not equal if their formatting or object
+     * attribute ordering differs (see {@link JSON} for details).
+     */
     @Override
     public String toString() {
         return String.valueOf(data);
diff --git a/jOOQ/src/main/java/org/jooq/JSONB.java b/jOOQ/src/main/java/org/jooq/JSONB.java
index 6524717ffe..ca2c8be72f 100644
--- a/jOOQ/src/main/java/org/jooq/JSONB.java
+++ b/jOOQ/src/main/java/org/jooq/JSONB.java
@@ -55,6 +55,25 @@ import org.jetbrains.annotations.Nullable;
  * 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.
+ * <p>
+ * Unlike the purely text based, formatting-preserving {@link JSON} data type,
+ * the {@link JSONB} type uses a normalised representation of the JSON content,
+ * meaning that e.g. the following two documents are equal, despite their
+ * different object attribute order and formatting:
+ * <p>
+ * <ul>
+ * <li><code>{"a":1,"b":2}</code></li>
+ * <li><code>{"b": 2, "a": 1}</code></li>
+ * </ul>
+ * <p>
+ * This impacts the behaviour (and performance!) of
+ * <ul>
+ * <li>{@link #equals(Object)}</li>
+ * <li>{@link #hashCode()}</li>
+ * <li>{@link #toString()}</li>
+ * </ul>
+ * <p>
+ * The {@link #data()} content, however, is not normalised.
  */
 public final class JSONB implements Serializable {
 
@@ -111,12 +130,36 @@ public final class JSONB implements Serializable {
         return parsed;
     }
 
+    // -------------------------------------------------------------------------
+    // The Object API
+    // -------------------------------------------------------------------------
+
+    /**
+     * {@inheritDoc}
+     * <p>
+     * <h3>{@link JSONB} specifics:</h3>
+     * <p>
+     * The {@link JSONB} type uses a normalised representation of the JSON
+     * content, meaning that two equivalent JSON documents are considered equal
+     * (see {@link JSONB} for details). This impacts both behaviour and
+     * performance!
+     */
     @Override
     public int hashCode() {
         Object p = parsed();
         return p == null ? 0 : p.hashCode();
     }
 
+    /**
+     * {@inheritDoc}
+     * <p>
+     * <h3>{@link JSONB} specifics:</h3>
+     * <p>
+     * The {@link JSONB} type uses a normalised representation of the JSON
+     * content, meaning that two equivalent JSON documents are considered equal
+     * (see {@link JSONB} for details). This impacts both behaviour and
+     * performance!
+     */
     @Override
     public boolean equals(Object obj) {
         if (this == obj)
@@ -126,6 +169,16 @@ public final class JSONB implements Serializable {
         return false;
     }
 
+    /**
+     * {@inheritDoc}
+     * <p>
+     * <h3>{@link JSONB} specifics:</h3>
+     * <p>
+     * The {@link JSONB} type uses a normalised representation of the JSON
+     * content, meaning that two equivalent JSON documents are considered equal
+     * (see {@link JSONB} for details). This impacts both behaviour and
+     * performance!
+     */
     @Override
     public String toString() {
         return JSONValue.toJSONString(parsed());