diff --git a/hibernate-core/src/main/java/org/hibernate/NaturalIdMutability.java b/hibernate-core/src/main/java/org/hibernate/NaturalIdMutability.java
index 0257aa70f5..eb721aafdf 100644
--- a/hibernate-core/src/main/java/org/hibernate/NaturalIdMutability.java
+++ b/hibernate-core/src/main/java/org/hibernate/NaturalIdMutability.java
@@ -27,6 +27,8 @@ package org.hibernate;
* Possible values regarding the mutability of a natural id.
*
* @author Steve Ebersole
+ *
+ * @see org.hibernate.annotations.NaturalId
*/
public enum NaturalIdMutability {
/**
@@ -34,12 +36,14 @@ public enum NaturalIdMutability {
* the entity to the database. Also, it will invalidate any caching when such a change is detected.
*/
MUTABLE,
+
/**
* The natural id is immutable. Hibernate will ignore any changes in the natural id value when flushing updates
* to the entity to the database. Additionally Hibernate will not check with the database to check if the
* natural id values change there. Essentially the user is assuring Hibernate that the values will not change.
*/
IMMUTABLE,
+
/**
* The natural id is immutable. Hibernate will ignore any changes in the natural id value when flushing updates
* to the entity to the database. However, Hibernate will check with the database to check if the natural
@@ -50,5 +54,12 @@ public enum NaturalIdMutability {
* as such. The overhead of maintaining caching of natural ids in these cases is far greater than the benefit
* from such caching. In such cases, a database index is a much better solution.
*/
- IMMUTABLE_CHECKED
+ IMMUTABLE_CHECKED,
+
+ /**
+ * @deprecated Added in deprecated form solely to allow seamless working until the deprecated attribute
+ * {@link org.hibernate.annotations.NaturalId#mutable()} can be removed.
+ */
+ @Deprecated
+ UNSPECIFIED
}
diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/NaturalId.java b/hibernate-core/src/main/java/org/hibernate/annotations/NaturalId.java
index 6755eb34ad..ed39c1460b 100644
--- a/hibernate-core/src/main/java/org/hibernate/annotations/NaturalId.java
+++ b/hibernate-core/src/main/java/org/hibernate/annotations/NaturalId.java
@@ -54,9 +54,13 @@ public @interface NaturalId {
boolean mutable() default false;
/**
- * The mutability behavior of this natural id
+ * The mutability behavior of this natural id.
+ *
+ * Note: the current default value is the {@link NaturalIdMutability#UNSPECIFIED} value which was added
+ * in deprecated form until the deprecated {@link #mutable()} attribute here can be removed. This lets existing
+ * applications continue to work seamlessly using their existing natural id annotations.
*
* @return The mutability behavior.
*/
- NaturalIdMutability mutability();
+ NaturalIdMutability mutability() default NaturalIdMutability.UNSPECIFIED;
}