Add schema registry singleton class

Author: Levi-Armstrong

tesseract_common/CMakeLists.txt

@@ -96,8 +96,9 @@ add_library(
   src/profile.cpp
   src/property_tree.cpp
   src/resource_locator.cpp
-  src/types.cpp
+  src/schema_registry.cpp
   src/stopwatch.cpp
+  src/types.cpp
   src/timer.cpp
   src/yaml_utils.cpp)
 target_link_libraries(

tesseract_common/include/tesseract_common/property_tree.h

@@ -2,9 +2,11 @@
 #define TESSERACT_COMMON_PROPERTY_TREE_H
 
 #include <string>
+#include <string_view>
 #include <map>
-#include <optional>
 #include <vector>
+#include <optional>
+#include <functional>
 #include <yaml-cpp/yaml.h>
 
 namespace tesseract_common
@@ -14,7 +16,7 @@ namespace property_type
 constexpr std::string_view BOOL{ "bool" };
 constexpr std::string_view STRING{ "string" };
 constexpr std::string_view INT{ "int" };
-constexpr std::string_view FLAOT{ "float" };
+constexpr std::string_view FLOAT{ "float" };
 }  // namespace property_type
 
 namespace property_attribute
@@ -27,79 +29,90 @@ constexpr std::string_view MAXIMUM{ "maximum" };
 }  // namespace property_attribute
 
 /**
- * @brief A hierarchical property tree that stores values, metadata attributes,
- *        and supports schema merging, default handling, and custom validation.
+ * @file property_tree.h
+ * @brief Defines PropertyTree, a hierarchical structure for YAML-based
+ *        configuration with metadata and validation support.
+ */
+
+/**
+ * @class PropertyTree
+ * @brief Represents a node in a hierarchical property tree.
  *
- * Each node may contain:
+ * Each PropertyTree node may contain:
  *  - A YAML::Node value (scalar, sequence, or map)
- *  - Metadata attributes (as a map of YAML::Node)
- *  - Child PropertyTree nodes for nested structures
- *  - Custom validator functions to enforce constraints
+ *  - A map of metadata attributes (YAML::Node) keyed by string
+ *  - Nested child PropertyTree nodes
+ *  - A list of custom validator functions
  */
 class PropertyTree
 {
 public:
   /**
-   * @brief Signature for custom validator functions.
+   * @brief Signature for custom validator callbacks.
    * @param node   The PropertyTree node being validated.
+   * @throws std::runtime_error on validation failure.
    */
   using ValidatorFn = std::function<void(const PropertyTree&)>;
 
   /**
-   * @brief Default constructor.
+   * @brief Default constructor. Creates an empty tree node.
    */
   PropertyTree() = default;
 
   /**
-   * @brief Merge a schema tree into this node.
-   *    * Copies schema attributes, applies non-required defaults,
-   * merges child structure, and registers schema validators.
-   * @param schema The schema node to merge from.
+   * @brief Merge schema metadata into this node.
+   *
+   * Copies attributes from the schema, applies defaults for non-required
+   * properties, registers schema validators, and recursively merges children.
+   * @param schema  PropertyTree containing schema definitions.
    */
   void mergeSchema(const PropertyTree& schema);
 
   /**
-   * @brief Validate this tree using registered validators.
-   *    * Traverses the tree, invoking each node's validators.
+   * @brief Validate the tree using registered validators.
+   *
+   * Recursively invokes all validators on this node and its children.
+   * Throws on the first error encountered.
    */
   void validate() const;
 
   /**
    * @brief Register a custom validator for this node.
-   * @param fn Validator function to invoke during validate().
+   * @param fn  Callback to invoke during validation.
    */
   void addValidator(ValidatorFn fn);
 
   /**
    * @brief Access or create a child node by key.
-   * @param key Child node identifier.
-   * @return Reference to the child node.
+   * @param key  Child identifier (string key).
+   * @return Reference to the child PropertyTree.
    */
   PropertyTree& get(std::string_view key);
 
   /**
    * @brief Access a child node by key (const).
-   * @param key Child node identifier.
-   * @return Const reference to the child node.
+   * @param key  Child identifier.
+   * @return Const reference to the child.
+   * @throws std::out_of_range if key not found.
    */
   const PropertyTree& get(std::string_view key) const;
 
   /**
    * @brief Find a child node without creating it.
-   * @param key Child node identifier.
-   * @return Pointer to the child or nullptr if missing.
+   * @param key  Child identifier.
+   * @return Pointer to child or nullptr if not present.
    */
   const PropertyTree* find(std::string_view key) const;
 
   /**
-   * @brief Set the YAML value for this node.
-   * @param v YAML::Node representing the value.
+   * @brief Set the YAML value of this node.
+   * @param v  YAML::Node representing the new value.
    */
   void setValue(const YAML::Node& v);
 
   /**
-   * @brief Get the YAML value stored in this node.
-   * @return Const reference to YAML::Node.
+   * @brief Retrieve the YAML value stored at this node.
+   * @return Const reference to a YAML::Node.
    */
   const YAML::Node& getValue() const;
 
@@ -110,98 +123,84 @@ class PropertyTree
   std::vector<std::string> keys() const;
 
   /**
-   * @brief Set a metadata attribute (YAML::Node form).
+   * @brief Set a metadata attribute (YAML node form).
    * @param name  Attribute name.
    * @param attr  YAML::Node value.
    */
   void setAttribute(std::string_view name, const YAML::Node& attr);
 
-  /**
-   * @brief Set a string attribute.
-   * @param name  Attribute name.
-   * @param attr  String value.
-   */
+  /** @brief Convenience overload to set a string attribute. */
   void setAttribute(std::string_view name, std::string_view attr);
-
-  /**
-   * @brief Set a C-string attribute.
-   */
   void setAttribute(std::string_view name, const char* attr);
-
-  /**
-   * @brief Set a boolean attribute.
-   */
+  /** @brief Set a boolean attribute. */
   void setAttribute(std::string_view name, bool attr);
-
-  /**
-   * @brief Set an integer attribute.
-   */
+  /** @brief Set an integer attribute. */
   void setAttribute(std::string_view name, int attr);
-
-  /**
-   * @brief Set a double attribute.
-   */
+  /** @brief Set a double attribute. */
   void setAttribute(std::string_view name, double attr);
 
   /**
-   * @brief Check if an attribute exists and is non-null.
-   * @param name Attribute name.
-   * @return True if present and non-null.
+   * @brief Check if an attribute exists and is not null.
+   * @param name  Attribute name.
+   * @return True if present and non-null, false otherwise.
    */
   bool hasAttribute(std::string_view name) const;
 
   /**
-   * @brief Retrieve an attribute value.
-   * @param name Attribute name.
-   * @return Optional<YAML::Node> if attribute exists.
+   * @brief Retrieve an attribute value by name.
+   * @param name  Attribute name.
+   * @return Optional containing YAML::Node if found.
    */
   std::optional<YAML::Node> getAttribute(std::string_view name) const;
 
   /**
    * @brief List all metadata attribute keys.
-   * @return Vector of attribute key strings.
+   * @return Vector of attribute names.
    */
   std::vector<std::string> getAttributeKeys() const;
 
   /**
-   * @brief Build a PropertyTree from a YAML::Node.
-   * @param node Root YAML::Node.
+   * @brief Create a PropertyTree from a YAML::Node.
+   * @param node  Root YAML::Node to convert.
    * @return Populated PropertyTree hierarchy.
    */
   static PropertyTree fromYAML(const YAML::Node& node);
 
   /**
-   * @brief Serialize this tree to a YAML::Node.
-   * @param exclude_attributes If true, omit the attributes map.
+   * @brief Serialize this tree back into a YAML::Node.
+   * @param exclude_attributes  If true, omit the attributes map.
    * @return YAML::Node representation of the tree.
    */
   YAML::Node toYAML(bool exclude_attributes = true) const;
 
 private:
-  YAML::Node value_;                             /**< Stored YAML value */
+  YAML::Node value_;                             /**< Value stored at this node */
   std::map<std::string, YAML::Node> attributes_; /**< Metadata attributes */
   std::map<std::string, PropertyTree> children_; /**< Nested child nodes */
-  std::vector<ValidatorFn> validators_;          /**< Registered validators */
+  std::vector<ValidatorFn> validators_;          /**< Validators to invoke */
 };
 
 /**
- * @brief Ensure a required attribute exists and is non-null.
- * @param node PropertyTree node to validate.
+ * @brief Validator: ensure 'required' attribute is present and non-null.
+ * @param node  Node to validate.
+ * @throws runtime_error if missing.
  */
 void validateRequired(const PropertyTree& node);
 
 /**
- * @brief Enforce numeric range if 'minimum'/'maximum' attributes are set.
- * @param node PropertyTree node to validate.
+ * @brief Validator: enforce 'minimum'/'maximum' range constraints.
+ * @param node  Node to validate.
+ * @throws runtime_error if out of range.
  */
 void validateRange(const PropertyTree& node);
 
 /**
- * @brief Enforce that the node's value is one of the 'enum' attribute list.
- * @param node PropertyTree node to validate.
+ * @brief Validator: enforce that node's value is in 'enum' list.
+ * @param node  Node to validate.
+ * @throws runtime_error if not found.
  */
 void validateEnum(const PropertyTree& node);
 
 }  // namespace tesseract_common
 
-#endif  // PROPERTY_TREE_H
+#endif  // TESSERACT_COMMON_PROPERTY_TREE_H

tesseract_common/include/tesseract_common/schema_registry.h

@@ -0,0 +1,77 @@
+#ifndef TESSERACT_COMMON_SCHEMA_REGISTRY_H
+#define TESSERACT_COMMON_SCHEMA_REGISTRY_H
+
+#include <string>
+#include <map>
+#include <mutex>
+#include <memory>
+
+namespace tesseract_common
+{
+class PropertyTree;
+
+/**
+ * @brief A global registry of named schemas for PropertyTree.
+ *
+ * Use SchemaRegistry::instance() to access the singleton.
+ */
+class SchemaRegistry
+{
+public:
+  ~SchemaRegistry() = default;
+  SchemaRegistry(const SchemaRegistry&) = delete;
+  SchemaRegistry& operator=(const SchemaRegistry&) = delete;
+  SchemaRegistry(const SchemaRegistry&&) = delete;
+  SchemaRegistry& operator=(const SchemaRegistry&&) = delete;
+
+  /** @brief Access the singleton instance. */
+  static std::shared_ptr<SchemaRegistry> instance();
+
+  /**
+   * @brief Register an already-parsed schema under a logical key.
+   * @param key    Unique identifier for this schema.
+   * @param schema Parsed PropertyTree schema.
+   */
+  void registerSchema(const std::string& key, const PropertyTree& schema);
+
+  /**
+   * @brief Register a schema from a YAML file path.
+   * @param key   Unique identifier for this schema.
+   * @param path  Path to a .yaml schema file.
+   */
+  void registerSchemaFromFile(const std::string& key, const std::string& path);
+
+  /**
+   * @brief Check whether a schema is registered under this key.
+   * @param key  Logical identifier.
+   * @return True if present.
+   */
+  bool contains(const std::string& key) const;
+
+  /**
+   * @brief Retrieve a registered schema by key.
+   * @param key Logical identifier.
+   * @return Const reference to the schema PropertyTree.
+   * @throws std::out_of_range if the key is not found.
+   */
+  const PropertyTree& get(const std::string& key) const;
+
+  /**
+   * @brief Load and parse an arbitrary YAML file into a PropertyTree.
+   * @param path  Path to a .yaml file.
+   * @return Parsed PropertyTree.
+   * @throws YAML::Exception on parse errors.
+   */
+  static PropertyTree loadFile(const std::string& path);
+
+private:
+  SchemaRegistry() = default;
+
+  mutable std::mutex mutex_;
+  mutable std::map<std::string, PropertyTree> schemas_;
+  mutable std::map<std::string, std::string> paths_;
+};
+
+}  // namespace tesseract_common
+
+#endif  // TESSERACT_COMMON_SCHEMA_REGISTRY_H

tesseract_common/src/property_tree.cpp

@@ -1,7 +1,9 @@
 #include <tesseract_common/property_tree.h>
+#include <tesseract_common/schema_registry.h>
 
 const static std::string ATTRIBUTES_KEY{ "attributes" };
 const static std::string VALUE_KEY{ "value" };
+const static std::string FOLLOW_KEY{ "follow" };
 
 namespace tesseract_common
 {
@@ -132,6 +134,17 @@ std::vector<std::string> PropertyTree::getAttributeKeys() const
 
 PropertyTree PropertyTree::fromYAML(const YAML::Node& node)
 {
+  // Handle 'follow' directive: load external YAML or schema file
+  if (node.IsMap() && node[FOLLOW_KEY] && node[FOLLOW_KEY].IsScalar())
+  {
+    if (node.size() > 1)
+      throw std::runtime_error("'follow' cannot be mixed with other entries");
+
+    auto key = node[FOLLOW_KEY].as<std::string>();
+    auto registry = SchemaRegistry::instance();
+    return registry->contains(key) ? registry->get(key) : SchemaRegistry::loadFile(key);
+  }
+
   PropertyTree tree;
   tree.value_ = node;
   if (node.IsMap())