JSON: Selectively suppress unknown key warnings (#1700)

* Add functionality to selectively suppress key warnings

For unknown keys.

{
  "dont_warn_unused_keys": [
    "key1",
    "key3"
  ],
  "key1": 5,
  "key2": {
    "dont_warn_unused_keys": [
      "key1"
    ],
    "key1": 5,
    "key2": 6
  },
  "key3": {
    "dont_warn_unused_keys": [
      "key1"
    ],
    "key1": 5,
    "key2": 6
  }
}

Will yield the warning:

[Series] The following parts of the global JSON config remains unused:
{
  "key2": {
    "dont_warn_unused_keys": [
      "key1"
    ],
    "key1": 5,
    "key2": 6
  },
  "key3": {
    "key2": 6
  }
}

TODO: Better errors when parsing, documentation

* init(): Treat the original JSON val as const

* Documentation

* Bugfix

* More precise error messages

Author: franzpoeschel

docs/source/details/backendconfig.rst

@@ -101,6 +101,42 @@ For JSON and ADIOS2, all datasets are resizable, independent of this option.
 
 The key ``rank_table`` allows specifying the creation of a **rank table**, used for tracking :ref:`chunk provenance especially in streaming setups <rank_table>`, refer to the streaming documentation for details.
 
+A warning is printed if the JSON/TOML configuration contains keys that are not understood (and hence ignored) by the openPMD-api.
+Such warnings can be suppressed by listing key names under ``"dont_warn_unused_keys"``.
+
+Example:
+
+  .. code-block:: json
+
+    {
+      "adio2": {
+        "dataset": {
+          "put dataset options": "here"
+        }
+      },
+      "hdf5": {
+        "an unknown": "key",
+        "another unknown": "key",
+        "a third unknown": "key",
+        "dont_warn_unused_keys": ["an unknown", "another unknown"]
+      }
+    }
+
+The openPMD-api will warn about the unknown key ``"adio2"`` (in order to give feedback about the apparent misspelling of ``"adios2"`` to users); there will similarly be a warning for the unknown HDF5 key ``"a third unknown"``. Warnings about the other two unknown keys have been suppressed. The printed warning will hence be about these unknown parts of the JSON configuration:
+
+  .. code-block:: json
+
+    {
+      "adio2": {
+        "dataset": {
+          "put dataset options": "here"
+        }
+      },
+      "hdf5": {
+        "a third unknown": "key"
+      }
+    }
+
 Configuration Structure per Backend
 -----------------------------------
 

include/openPMD/auxiliary/JSON_internal.hpp

@@ -23,6 +23,7 @@
 
 #include "openPMD/config.hpp"
 
+#include <deque>
 #include <nlohmann/json.hpp>
 #include <toml.hpp>
 
@@ -150,6 +151,11 @@ namespace json
          *
          */
         nlohmann::json *m_positionInShadow;
+        /**
+         * @brief (Redundantly) track the current path within the JSON value.
+         *        Used (currently) only for more precise error messages.
+         */
+        std::deque<std::string> m_positionForErrorMessages;
         bool m_trace = true;
 
         void invertShadow(
@@ -160,8 +166,20 @@ namespace json
             std::shared_ptr<nlohmann::json> shadow,
             nlohmann::json *positionInOriginal,
             nlohmann::json *positionInShadow,
+            std::deque<std::string> positionForErrorMessages,
             SupportedLanguages originallySpecifiedAs,
             bool trace);
+
+        void init();
+        /*
+         * Called upon each traced access of a location in the JSON value, along
+         * with the matching subtree of the shadow.
+         * This implements the `dont_warn_unused_keys` functionality.
+         */
+        static void init(
+            nlohmann::json const &original,
+            nlohmann::json &shadow,
+            std::deque<std::string> &positionForErrorMessages);
     };
 
     template <typename Key>
@@ -178,11 +196,14 @@ namespace json
             newPositionInShadow = &m_positionInShadow->operator[](key);
         }
         bool traceFurther = newPositionInOriginal->is_object();
+        auto new_path = m_positionForErrorMessages;
+        new_path.push_back(std::forward<Key>(key));
         return TracingJSON(
             m_originalJSON,
             m_shadow,
             newPositionInOriginal,
             newPositionInShadow,
+            std::move(new_path),
             originallySpecifiedAs,
             traceFurther);
     }

src/auxiliary/JSON.cpp

@@ -53,7 +53,9 @@ TracingJSON::TracingJSON(
     , m_shadow(std::make_shared<nlohmann::json>())
     , m_positionInOriginal(&*m_originalJSON)
     , m_positionInShadow(&*m_shadow)
-{}
+{
+    init();
+}
 
 TracingJSON::TracingJSON(ParsedConfig parsedConfig)
     : TracingJSON{
@@ -150,15 +152,87 @@ TracingJSON::TracingJSON(
     std::shared_ptr<nlohmann::json> shadow,
     nlohmann::json *positionInOriginal,
     nlohmann::json *positionInShadow,
+    std::deque<std::string> positionForErrorMessages,
     SupportedLanguages originallySpecifiedAs_in,
     bool trace)
     : originallySpecifiedAs(originallySpecifiedAs_in)
     , m_originalJSON(std::move(originalJSON))
     , m_shadow(std::move(shadow))
     , m_positionInOriginal(positionInOriginal)
     , m_positionInShadow(positionInShadow)
+    , m_positionForErrorMessages(std::move(positionForErrorMessages))
     , m_trace(trace)
-{}
+{
+    init();
+}
+
+void TracingJSON::init()
+{
+    if (m_originalJSON)
+    {
+        init(
+            *m_positionInOriginal,
+            *m_positionInShadow,
+            m_positionForErrorMessages);
+    }
+}
+
+void TracingJSON::init(
+    nlohmann::json const &original,
+    nlohmann::json &shadow,
+    std::deque<std::string> &positionForErrorMessages)
+{
+    if (original.is_object() && original.contains("dont_warn_unused_keys"))
+    {
+        auto suppress_warnings_for_these_json =
+            original.at("dont_warn_unused_keys");
+        auto suppress_warnings_for_these = [&]() {
+            try
+            {
+                return suppress_warnings_for_these_json
+                    .get<std::vector<std::string>>();
+            }
+            catch (nlohmann::json::type_error const &e)
+            {
+                std::vector<std::string> errorPath;
+                errorPath.reserve(positionForErrorMessages.size() + 1);
+                for (auto const &val : positionForErrorMessages)
+                {
+                    errorPath.push_back(val);
+                }
+                errorPath.emplace_back("dont_warn_unused_keys");
+                throw error::BackendConfigSchema(
+                    errorPath,
+                    "Key `dont_warn_unused_keys` must be a list of strings, "
+                    "original error was: " +
+                        std::string(e.what()));
+            }
+        }();
+        for (auto const &key : suppress_warnings_for_these)
+        {
+            // For each suppressed key, we now emulate an access to that
+            // key. This entails calling init() recursively since that
+            // function is called upon each access to a traced key.
+            auto it = original.find(key);
+            if (it == original.end())
+            {
+                continue;
+            }
+            positionForErrorMessages.push_back(key);
+            try
+            {
+                init(*it, shadow[key], positionForErrorMessages);
+            }
+            catch (...)
+            {
+                positionForErrorMessages.pop_back();
+                throw;
+            }
+            positionForErrorMessages.pop_back();
+        }
+        shadow["dont_warn_unused_keys"] = nlohmann::json();
+    }
+}
 
 namespace
 {