diff --git a/components/config/definition.rst b/components/config/definition.rst
index 77898e6b576..293da6b0b9b 100644
--- a/components/config/definition.rst
+++ b/components/config/definition.rst
@@ -325,6 +325,11 @@ The separator used in keys is typically ``_`` in Yaml and ``-`` in XML. For
 example, ``auto_connect`` in Yaml and ``auto-connect``. The normalization would
 make both of these ``auto_connect``.
 
+.. caution::
+
+    The target key will not be altered if it's mixed like 
+    ``foo-bar_moo`` or if it already exists.
+
 Another difference between Yaml and XML is in the way arrays of values may
 be represented. In Yaml you may have: