feat: opt-in unknown key validation for ConfigBeanFactory (#851)

mattheworford · web-flow · commit 81f2de09c907 · 2026-06-03T10:41:22.000+02:00
diff --git a/README.md b/README.md
@@ -484,7 +484,9 @@ config matches the bean's implied schema. Bean fields can be
 primitive types, typed lists such as `List<Integer>`,
 `java.time.Duration`, `ConfigMemorySize`, or even a raw `Config`,
 `ConfigObject`, or `ConfigValue` (if you'd like to deal with a
-particular value manually).
+particular value manually). By default, config keys that do not map
+to a bean property are ignored. To reject unknown keys, use the
+`ConfigBeanFactory.create(config, MyBean.class, false)` overload.
 
 ## Using HOCON, the JSON Superset
 
diff --git a/config/src/main/java/com/typesafe/config/ConfigBeanFactory.java b/config/src/main/java/com/typesafe/config/ConfigBeanFactory.java
@@ -39,11 +39,52 @@ public class ConfigBeanFactory {
      * @throws ConfigException.BadBean
      *     If something is wrong with the JavaBean
      * @throws ConfigException.ValidationFailed
-     *     If the config doesn't conform to the bean's implied schema
+     *     If the config doesn't conform to the bean's implied schema. Unknown
+     *     config keys are ignored.
      * @throws ConfigException
      *     Can throw the same exceptions as the getters on <code>Config</code>
      */
     public static <T> T create(Config config, Class<T> clazz) {
-        return ConfigBeanImpl.createInternal(config, clazz);
+        return ConfigBeanImpl.createInternal(config, clazz, true);
+    }
+
+    /**
+     * Creates an instance of a class, initializing its fields from a {@link Config}.
+     *
+     * Example usage:
+     *
+     * <pre>
+     * Config configSource = ConfigFactory.load().getConfig("foo");
+     * FooConfig config = ConfigBeanFactory.create(configSource, FooConfig.class, false);
+     * </pre>
+     *
+     * The Java class should follow JavaBean conventions. Field types
+     * can be any of the types you can normally get from a {@link
+     * Config}, including <code>java.time.Duration</code> or {@link
+     * ConfigMemorySize}. Fields may also be another JavaBean-style
+     * class.
+     *
+     * Fields are mapped to config by converting the config key to
+     * camel case.  So the key <code>foo-bar</code> becomes JavaBean
+     * setter <code>setFooBar</code>.
+     *
+     * @since 1.4.9
+     *
+     * @param config source of config information
+     * @param clazz class to be instantiated
+     * @param allowUnknownConfigKeys if false, throw a validation error when
+     *     the config has keys that do not map to bean properties
+     * @param <T> the type of the class to be instantiated
+     * @return an instance of the class populated with data from the config
+     * @throws ConfigException.BadBean
+     *     If something is wrong with the JavaBean
+     * @throws ConfigException.ValidationFailed
+     *     If the config doesn't conform to the bean's implied schema, including
+     *     unknown config keys when <code>allowUnknownConfigKeys</code> is false
+     * @throws ConfigException
+     *     Can throw the same exceptions as the getters on <code>Config</code>
+     */
+    public static <T> T create(Config config, Class<T> clazz, boolean allowUnknownConfigKeys) {
+        return ConfigBeanImpl.createInternal(config, clazz, allowUnknownConfigKeys);
     }
 }
diff --git a/config/src/main/java/com/typesafe/config/impl/ConfigBeanImpl.java b/config/src/main/java/com/typesafe/config/impl/ConfigBeanImpl.java
@@ -40,7 +40,7 @@ public class ConfigBeanImpl {
      * @param clazz class of the bean
      * @return the bean instance
      */
-    public static <T> T createInternal(Config config, Class<T> clazz) {
+    public static <T> T createInternal(Config config, Class<T> clazz, boolean allowUnknownConfigKeys) {
         if (((SimpleConfig)config).root().resolveStatus() != ResolveStatus.RESOLVED)
             throw new ConfigException.NotResolved(
                     "need to Config#resolve() a config before using it to initialize a bean, see the API docs for Config#resolve()");
@@ -76,10 +76,26 @@ public static <T> T createInternal(Config config, Class<T> clazz) {
                 }
                 beanProps.add(beanProp);
             }
+            Set<String> beanPropNames = new HashSet<String>();
+            for (PropertyDescriptor beanProp : beanProps) {
+                beanPropNames.add(beanProp.getName());
+            }
 
             // Try to throw all validation issues at once (this does not comprehensively
             // find every issue, but it should find common ones).
             List<ConfigException.ValidationProblem> problems = new ArrayList<ConfigException.ValidationProblem>();
+            if (!allowUnknownConfigKeys) {
+                for (Map.Entry<String, String> nameEntry : originalNames.entrySet()) {
+                    String camelName = nameEntry.getKey();
+                    if (!beanPropNames.contains(camelName)) {
+                        AbstractConfigValue configValue = configProps.get(camelName);
+                        problems.add(new ConfigException.ValidationProblem(
+                                Path.newKey(nameEntry.getValue()).render(),
+                                configValue.origin(),
+                                "Unknown config setting"));
+                    }
+                }
+            }
             for (PropertyDescriptor beanProp : beanProps) {
                 Method setter = beanProp.getWriteMethod();
                 Class<?> parameterClass = setter.getParameterTypes()[0];
@@ -121,7 +137,8 @@ public static <T> T createInternal(Config config, Class<T> clazz) {
                     // Otherwise, raise a {@link Missing} exception right here
                     throw new ConfigException.Missing(beanProp.getName());
                 }
-                Object unwrapped = getValue(clazz, parameterType, parameterClass, config, configPropName);
+                Object unwrapped = getValue(clazz, parameterType, parameterClass, config, configPropName,
+                        allowUnknownConfigKeys);
                 setter.invoke(bean, unwrapped);
             }
             return bean;
@@ -145,7 +162,7 @@ public static <T> T createInternal(Config config, Class<T> clazz) {
     // types plus you can always use Object, ConfigValue, Config,
     // ConfigObject, etc.  as an escape hatch.
     private static Object getValue(Class<?> beanClass, Type parameterType, Class<?> parameterClass, Config config,
-            String configPropName) {
+            String configPropName, boolean allowUnknownConfigKeys) {
         if (parameterClass == Boolean.class || parameterClass == boolean.class) {
             return config.getBoolean(configPropName);
         } else if (parameterClass == Integer.class || parameterClass == int.class) {
@@ -163,9 +180,11 @@ private static Object getValue(Class<?> beanClass, Type parameterType, Class<?>
         } else if (parameterClass == Object.class) {
             return config.getAnyRef(configPropName);
         } else if (parameterClass == List.class) {
-            return getListValue(beanClass, parameterType, parameterClass, config, configPropName);
+            return getListValue(beanClass, parameterType, parameterClass, config, configPropName,
+                    allowUnknownConfigKeys);
         } else if (parameterClass == Set.class) {
-            return getSetValue(beanClass, parameterType, parameterClass, config, configPropName);
+            return getSetValue(beanClass, parameterType, parameterClass, config, configPropName,
+                    allowUnknownConfigKeys);
         } else if (parameterClass == Map.class) {
             // we could do better here, but right now we don't.
             Type[] typeArgs = ((ParameterizedType)parameterType).getActualTypeArguments();
@@ -186,17 +205,20 @@ private static Object getValue(Class<?> beanClass, Type parameterType, Class<?>
             Enum enumValue = config.getEnum((Class<Enum>) parameterClass, configPropName);
             return enumValue;
         } else if (hasAtLeastOneBeanProperty(parameterClass)) {
-            return createInternal(config.getConfig(configPropName), parameterClass);
+            return createInternal(config.getConfig(configPropName), parameterClass, allowUnknownConfigKeys);
         } else {
             throw new ConfigException.BadBean("Bean property " + configPropName + " of class " + beanClass.getName() + " has unsupported type " + parameterType);
         }
     }
 
-    private static Object getSetValue(Class<?> beanClass, Type parameterType, Class<?> parameterClass, Config config, String configPropName) {
-        return new HashSet((List) getListValue(beanClass, parameterType, parameterClass, config, configPropName));
+    private static Object getSetValue(Class<?> beanClass, Type parameterType, Class<?> parameterClass, Config config,
+            String configPropName, boolean allowUnknownConfigKeys) {
+        return new HashSet((List) getListValue(beanClass, parameterType, parameterClass, config, configPropName,
+                allowUnknownConfigKeys));
     }
 
-    private static Object getListValue(Class<?> beanClass, Type parameterType, Class<?> parameterClass, Config config, String configPropName) {
+    private static Object getListValue(Class<?> beanClass, Type parameterType, Class<?> parameterClass, Config config,
+            String configPropName, boolean allowUnknownConfigKeys) {
         Type elementType = ((ParameterizedType)parameterType).getActualTypeArguments()[0];
 
         if (elementType == Boolean.class) {
@@ -229,7 +251,7 @@ private static Object getListValue(Class<?> beanClass, Type parameterType, Class
             List<Object> beanList = new ArrayList<Object>();
             List<? extends Config> configList = config.getConfigList(configPropName);
             for (Config listMember : configList) {
-                beanList.add(createInternal(listMember, (Class<?>) elementType));
+                beanList.add(createInternal(listMember, (Class<?>) elementType, allowUnknownConfigKeys));
             }
             return beanList;
         } else {
diff --git a/config/src/test/scala/com/typesafe/config/impl/ConfigBeanFactoryTest.scala b/config/src/test/scala/com/typesafe/config/impl/ConfigBeanFactoryTest.scala
@@ -72,6 +72,25 @@ class ConfigBeanFactoryTest extends TestUtils {
         assertEquals("yes", beanConfig.getYes)
     }
 
+    @Test
+    def testCreateAllowsUnknownConfigKeysByDefault() {
+        val beanConfig = ConfigBeanFactory.create(parseConfig("{abcd=abcd, yes=yes, nope=nope}"),
+            classOf[StringsConfig])
+        assertNotNull(beanConfig)
+        assertEquals("abcd", beanConfig.getAbcd)
+        assertEquals("yes", beanConfig.getYes)
+    }
+
+    @Test
+    def testCreateFailsOnUnknownConfigKeysWhenNotAllowed() {
+        val e = intercept[ConfigException.ValidationFailed] {
+            ConfigBeanFactory.create(parseConfig("{abcd=abcd, yes=yes, nope=nope}"), classOf[StringsConfig],
+                false)
+        }
+        assertTrue("unknown setting error", e.getMessage.contains("Unknown config setting"))
+        assertTrue("error about the right property", e.getMessage.contains("nope"))
+    }
+
     @Test
     def testCreateEnum() {
         val beanConfig: EnumsConfig = ConfigBeanFactory.create(loadConfig().getConfig("enums"), classOf[EnumsConfig])
