diff --git a/framework-docs/modules/ROOT/pages/core/appendix/xsd-schemas.adoc b/framework-docs/modules/ROOT/pages/core/appendix/xsd-schemas.adoc
index 28b79843a25a..38bccafbe276 100644
--- a/framework-docs/modules/ROOT/pages/core/appendix/xsd-schemas.adoc
+++ b/framework-docs/modules/ROOT/pages/core/appendix/xsd-schemas.adoc
@@ -565,6 +565,17 @@ is a convenience mechanism that sets up a xref:core/beans/factory-extension.adoc
  for you. If you need more control over the specific
 `PropertySourcesPlaceholderConfigurer` setup, you can explicitly define it as a bean yourself.
 
+[WARNING]
+=====
+Only one such element should be defined for a given application with the properties
+that it needs. Several property placeholders can be configured as long as they have distinct
+placeholder syntax (`${...}`).
+
+If you need to modularize the source of properties used for the replacement, you should
+not create multiple properties placeholders. Rather, each module should contribute a
+`PropertySource` to the `Environment`. Alternatively, you can create your own
+`PropertySourcesPlaceholderConfigurer` bean that gathers the properties to use.
+=====
 
 [[xsd-schemas-context-ac]]
 === Using `<annotation-config/>`
diff --git a/framework-docs/modules/ROOT/pages/core/beans/factory-extension.adoc b/framework-docs/modules/ROOT/pages/core/beans/factory-extension.adoc
index 3e7a095d9c8a..a82606dc0e9b 100644
--- a/framework-docs/modules/ROOT/pages/core/beans/factory-extension.adoc
+++ b/framework-docs/modules/ROOT/pages/core/beans/factory-extension.adoc
@@ -372,6 +372,17 @@ The `PropertySourcesPlaceholderConfigurer` not only looks for properties in the
 file you specify. By default, if it cannot find a property in the specified properties files,
 it checks against Spring `Environment` properties and regular Java `System` properties.
 
+[WARNING]
+=====
+Only one such element should be defined for a given application with the properties
+that it needs. Several property placeholders can be configured as long as they have distinct
+placeholder syntax (`${...}`).
+
+If you need to modularize the source of properties used for the replacement, you should
+not create multiple properties placeholders. Rather, you should create your own
+`PropertySourcesPlaceholderConfigurer` bean that gathers the properties to use.
+=====
+
 [TIP]
 =====
 You can use the `PropertySourcesPlaceholderConfigurer` to substitute class names, which