json-validator/include/jvalidate/validation_visitor.h

#pragma once

#include <algorithm>
#include <tuple>
#include <type_traits>
#include <vector>

#include <jvalidate/compat/enumerate.h>
#include <jvalidate/constraint/array_constraint.h>
#include <jvalidate/constraint/general_constraint.h>
#include <jvalidate/constraint/number_constraint.h>
#include <jvalidate/constraint/object_constraint.h>
#include <jvalidate/constraint/string_constraint.h>
#include <jvalidate/detail/expect.h>
#include <jvalidate/detail/iostream.h>
#include <jvalidate/detail/number.h>
#include <jvalidate/detail/pointer.h>
#include <jvalidate/detail/scoped_state.h>
#include <jvalidate/detail/string_adapter.h>
#include <jvalidate/format.h>
#include <jvalidate/forward.h>
#include <jvalidate/schema.h>
#include <jvalidate/status.h>
#include <jvalidate/validation_config.h>
#include <jvalidate/validation_result.h>

#define VISITED(type) std::get<std::unordered_set<type>>(*visited_)

#define VALIDATE_SUBSCHEMA_AND_MARK_LOCAL_VISIT(subschema, subinstance, path, local_visited, ...)  \
  do {                                                                                             \
    Status const partial =                                                                         \
        validate_subschema_on(subschema, subinstance, path __VA_OPT__(, ) __VA_ARGS__);            \
    rval &= partial;                                                                               \
    if (result_ and partial != Status::Noop) {                                                     \
      local_visited.insert(local_visited.end(), path);                                             \
    }                                                                                              \
  } while (false)

#define NOOP_UNLESS_TYPE(etype) RETURN_UNLESS(adapter::Type::etype == document.type(), Status::Noop)

#define BREAK_EARLY_IF_NO_RESULT_TREE()                                                            \
  do {                                                                                             \
    if (rval == Status::Reject and not result_ and not visited_) {                                 \
      break;                                                                                       \
    }                                                                                              \
  } while (false)

#define ANNOTATION_HELPER(name, ADD, FMT)                                                          \
  void name(auto const &... args) const {                                                          \
    if (not result_) {                                                                             \
      /* do nothing if there's no result object to append to */                                    \
    } else if (schema_path_.empty()) {                                                             \
      result_->ADD(where_, schema_path_, "", FMT(args...));                                        \
    } else {                                                                                       \
      result_->ADD(where_, schema_path_.parent(), schema_path_.back(), FMT(args...));              \
    }                                                                                              \
  }

namespace jvalidate {
JVALIDATE_TRIBOOL_TYPE(StoreResults, ForValid, ForInvalid, ForAnything);

template <Adapter Root, RegexEngine RE, typename ExtensionVisitor> class ValidationVisitor {
private:
  using VisitedAnnotation = std::tuple<std::unordered_set<size_t>, std::unordered_set<std::string>>;
  friend class ValidationVisitorTest;

private:
  detail::Pointer where_;
  detail::Pointer schema_path_;

  schema::Node const * schema_;
  Root const * root_;

  ValidationResult * result_;

  ValidationConfig const & cfg_;
  ExtensionVisitor extension_;
  RE & regex_;
  FormatValidator & format_;

  mutable VisitedAnnotation * visited_ = nullptr;
  mutable StoreResults tracking_ = StoreResults::ForInvalid;

public:
  /**
   * @brief Construct a new ValidationVisitor
   *
   * @param schema The parsed JSON Schema
   * @param cfg General configuration settings for how the run is executed
   * @param regex A cache of string regular expressions to compiled
   * regular expressions
   * @param[optional] extension A special visitor for extension constraints.
   * @param[optional] result A cache of result/annotation info for the user to
   * receive a detailed summary of why a document is supported/unsupported.
   */
  ValidationVisitor(schema::Node const & schema, Root const & root, ValidationConfig const & cfg,
                    RE & regex, FormatValidator & format, ExtensionVisitor extension,
                    ValidationResult * result)
      : schema_(&schema), root_(&root), result_(result), cfg_(cfg), extension_(extension),
        regex_(regex), format_(format) {}

private:
  Status visit(constraint::ExtensionConstraint const & cons, Adapter auto const & document) const {
    // Because we don't provide any contract constraint on our ExtensionVisitor,
    // we instead defer it to here where we validate that the extension can be
    // validated given the input document.
    // This covers a case where we write the extension around a specific adapter
    // instead of generically.
    if constexpr (std::is_invocable_r_v<Status, ExtensionVisitor, decltype(cons),
                                        decltype(document), ValidationVisitor const &>) {
      return extension_(cons, document, *this);
    }
    annotate("unsupported extension");
    return Status::Noop;
  }

  Status visit(constraint::TypeConstraint const & cons, Adapter auto const & document) const {
    adapter::Type const type = document.type();

    for (adapter::Type const accept : cons.types) {
      if (type == accept) { // Simple case, types are equal
        return result(Status::Accept, type, " is in types [", cons.types, "]");
      }
      if (accept == adapter::Type::Number && type == adapter::Type::Integer) {
        // Number is a super-type of Integer, therefore all Integer values are
        // accepted by a `"type": "number"` schema.
        return result(Status::Accept, type, " is in types [", cons.types, "]");
      }
      if (accept == adapter::Type::Integer && type == adapter::Type::Number &&
          detail::is_json_integer(document.as_number())) {
        // Since the JSON specification does not distinguish between Number
        // and Integer, but JSON Schema does, we need to check that the number
        // is a whole integer that is representable within the system (64-bit).
        return result(Status::Accept, type, " is in types [", cons.types, "]");
      }
    }
    return result(Status::Reject, type, " is not in types [", cons.types, "]");
  }

  Status visit(constraint::ConstConstraint const & cons, Adapter auto const & document) const {
    auto is_equal = [this, &document](auto const & frozen) {
      return document.equals(frozen, cfg_.strict_equality);
    };
    if (cons.value->apply(is_equal)) {
      return result(Status::Accept, "matches value");
    }
    return result(Status::Reject, cons.value, " was expected");
  }

  Status visit(constraint::EnumConstraint const & cons, Adapter auto const & document) const {
    auto is_equal = [this, &document](auto const & frozen) {
      return document.equals(frozen, cfg_.strict_equality);
    };
    for (auto const & [index, option] : detail::enumerate(cons.enumeration)) {
      if (option->apply(is_equal)) {
        return result(Status::Accept, index);
      }
    }
    return result(Status::Reject, document, " value is not one of ", cons.enumeration);
  }

  Status visit(constraint::AllOfConstraint const & cons, Adapter auto const & document) const {
    Status rval = Status::Accept;

    std::set<size_t> unmatched;
    for (auto const & [index, subschema] : detail::enumerate(cons.children)) {
      if (auto stat = validate_subschema(subschema, document, index); stat == Status::Reject) {
        rval = Status::Reject;
        unmatched.insert(index);
      }
      BREAK_EARLY_IF_NO_RESULT_TREE();
    }

    if (rval == Status::Reject) {
      return result(rval, "does not validate subschemas ", unmatched);
    }
    return result(rval, "validates all subschemas");
  }

  Status visit(constraint::AnyOfConstraint const & cons, Adapter auto const & document) const {
    std::optional<size_t> first_validated;
    for (auto const & [index, subschema] : detail::enumerate(cons.children)) {
      if (validate_subschema(subschema, document, index)) {
        // This technically will produce different results when we're tracking
        // visited nodes, but in practice it doesn't actually matter which
        // subschema index we record in the annotation.
        first_validated = index;
      }
      if (not visited_ && first_validated.has_value()) {
        break;
      }
    }

    if (first_validated.has_value()) {
      return result(Status::Accept, "validates subschema ", *first_validated);
    }
    return result(Status::Reject, "validates none of the subschemas");
  }

  Status visit(constraint::OneOfConstraint const & cons, Adapter auto const & document) const {
    std::set<size_t> matches;

    for (auto const & [index, subschema] : detail::enumerate(cons.children)) {
      scoped_state(tracking_, StoreResults::ForAnything);
      if (validate_subschema(subschema, document, index)) {
        matches.insert(index);
      }
    }

    if (matches.empty()) {
      return result(Status::Reject, "validates no subschemas");
    }
    if (matches.size() > 1) {
      return result(Status::Reject, "validates multiple subschemas ", matches);
    }

    size_t const match = *matches.begin();
    for (size_t i = 0; result_ and i < cons.children.size(); ++i) {
      if (i != match) {
        result_->unannotate(where_, schema_path_ / i);
      }
    }
    return result(Status::Accept, "validates subschema ", match);
  }

  Status visit(constraint::NotConstraint const & cons, Adapter auto const & document) const {
    scoped_state(visited_, nullptr);
    scoped_state(tracking_, !tracking_);
    bool const rejected = validate_subschema(cons.child, document) == Status::Reject;

    return rejected;
  }

  Status visit(constraint::ConditionalConstraint const & cons,
               Adapter auto const & document) const {
    Status const if_true = [this, &cons, &document]() {
      scoped_state(tracking_, StoreResults::ForAnything);
      return validate_subschema(cons.if_constraint, document);
    }();

    annotate(if_true ? "valid" : "invalid");
    if (if_true) {
      return validate_subschema(cons.then_constraint, document, detail::parent, "then");
    }
    return validate_subschema(cons.else_constraint, document, detail::parent, "else");
  }

  Status visit(constraint::MaximumConstraint const & cons, Adapter auto const & document) const {
    switch (document.type()) {
    case adapter::Type::Integer:
      if (int64_t value = document.as_integer(); not cons(value)) {
        return result(Status::Reject, value, cons.exclusive ? " >= " : " > ", cons.value);
      } else {
        return result(Status::Accept, value, cons.exclusive ? " < " : " <= ", cons.value);
      }
    case adapter::Type::Number:
      if (double value = document.as_number(); not cons(value)) {
        return result(Status::Reject, value, cons.exclusive ? " >= " : " > ", cons.value);
      } else {
        return result(Status::Accept, value, cons.exclusive ? " < " : " <= ", cons.value);
      }
    default:
      return Status::Noop;
    }
  }

  Status visit(constraint::MinimumConstraint const & cons, Adapter auto const & document) const {
    switch (document.type()) {
    case adapter::Type::Integer:
      if (int64_t value = document.as_integer(); not cons(value)) {
        return result(Status::Reject, value, cons.exclusive ? " <= " : " < ", cons.value);
      } else {
        return result(Status::Accept, value, cons.exclusive ? " > " : " >= ", cons.value);
      }
    case adapter::Type::Number:
      if (double value = document.as_number(); not cons(value)) {
        return result(Status::Reject, value, cons.exclusive ? " <= " : " < ", cons.value);
      } else {
        return result(Status::Accept, value, cons.exclusive ? " > " : " >= ", cons.value);
      }
    default:
      return Status::Noop;
    }
  }

  Status visit(constraint::MultipleOfConstraint const & cons, Adapter auto const & document) const {
    adapter::Type const type = document.type();
    RETURN_UNLESS(type == adapter::Type::Number || type == adapter::Type::Integer, Status::Noop);

    if (double value = document.as_number(); not cons(value)) {
      return result(Status::Reject, value, " is not a multiple of ", cons.value);
    } else {
      return result(Status::Accept, value, " is a multiple of ", cons.value);
    }
  }

  Status visit(constraint::MaxLengthConstraint const & cons, Adapter auto const & document) const {
    NOOP_UNLESS_TYPE(String);
    std::string const str = document.as_string();
    if (int64_t len = detail::length(str); len > cons.value) {
      return result(Status::Reject, "string of length ", len, " is >", cons.value);
    } else {
      return result(Status::Accept, "string of length ", len, " is <=", cons.value);
    }
  }

  Status visit(constraint::MinLengthConstraint const & cons, Adapter auto const & document) const {
    NOOP_UNLESS_TYPE(String);
    std::string const str = document.as_string();
    if (int64_t len = detail::length(str); len < cons.value) {
      return result(Status::Reject, "string of length ", len, " is <", cons.value);
    } else {
      return result(Status::Accept, "string of length ", len, " is >=", cons.value);
    }
  }

  Status visit(constraint::PatternConstraint const & cons, Adapter auto const & document) const {
    NOOP_UNLESS_TYPE(String);

    std::string const str = document.as_string();
    annotate(regex_.engine_name());
    if (regex_.search(cons.regex, str)) {
      return result(Status::Accept, "string matches pattern /", cons.regex, "/");
    }
    return result(Status::Reject, "string does not match pattern /", cons.regex, "/");
  }

  Status visit(constraint::FormatConstraint const & cons, Adapter auto const & document) const {
    // https://json-schema.org/draft/2020-12/json-schema-validation#name-defined-formats
    NOOP_UNLESS_TYPE(String);

    annotate(cons.format);
    if (not cfg_.validate_format && not cons.is_assertion) {
      // Don't both validating formats if we're not in assertion mode
      // Assertion mode is specified either by using the appropriate "$vocab"
      // meta-schema or by requesting it in the ValidationConfig.
      return true; // TODO: I think this can be made into Noop
    }

    switch (format_(cons.format, cons.for_version, document.as_string())) {
    case FormatValidator::Status::Unimplemented:
      return result(Status::Reject, "unimplemented format '", cons.format, "'");
    case FormatValidator::Status::Invalid:
      return result(Status::Reject, "does not match format '", cons.format, "'");
    case FormatValidator::Status::Unknown:
    case FormatValidator::Status::Valid:
      return result(Status::Accept, "matches format '", cons.format, "'");
    }
  }

  Status visit(constraint::AdditionalItemsConstraint const & cons,
               Adapter auto const & document) const {
    NOOP_UNLESS_TYPE(Array);

    auto array = document.as_array();

    Status rval = Status::Accept;
    std::vector<size_t> items;
    for (size_t i = cons.applies_after_nth; i < array.size(); ++i) {
      VALIDATE_SUBSCHEMA_AND_MARK_LOCAL_VISIT(cons.subschema, array[i], i, items);
      BREAK_EARLY_IF_NO_RESULT_TREE();
    }

    annotate_list(items);
    return rval;
  }

  Status visit(constraint::ContainsConstraint const & cons, Adapter auto const & document) const {
    NOOP_UNLESS_TYPE(Array);

    auto array = document.as_array();
    size_t const minimum = cons.minimum.value_or(1);
    size_t const maximum = cons.maximum.value_or(array.size());
    size_t matches = 0;
    for (size_t i = 0; i < array.size(); ++i) {
      if (validate_subschema_on(cons.subschema, array[i], i)) {
        ++matches;
      }
    }

    if (matches < minimum) {
      return result(Status::Reject, "array contains <", minimum, " matching items");
    }
    if (matches > maximum) {
      return result(Status::Reject, "array contains >", maximum, " matching items");
    }
    return result(Status::Accept, "array contains ", matches, " matching items");
  }

  Status visit(constraint::MaxItemsConstraint const & cons, Adapter auto const & document) const {
    NOOP_UNLESS_TYPE(Array);
    if (size_t size = document.array_size(); size > cons.value) {
      return result(Status::Reject, "array of size ", size, " is >", cons.value);
    } else {
      return result(Status::Accept, "array of size ", size, " is <=", cons.value);
    }
  }

  Status visit(constraint::MinItemsConstraint const & cons, Adapter auto const & document) const {
    NOOP_UNLESS_TYPE(Array);
    if (size_t size = document.array_size(); size < cons.value) {
      return result(Status::Reject, "array of size ", size, " is <", cons.value);
    } else {
      return result(Status::Accept, "array of size ", size, " is >=", cons.value);
    }
  }

  Status visit(constraint::TupleConstraint const & cons, Adapter auto const & document) const {
    NOOP_UNLESS_TYPE(Array);

    Status rval = Status::Accept;

    std::vector<size_t> items;
    for (auto const & [index, item] : detail::enumerate(document.as_array())) {
      if (index >= cons.items.size()) {
        break;
      }
      VALIDATE_SUBSCHEMA_AND_MARK_LOCAL_VISIT(cons.items[index], item, index, items);
      BREAK_EARLY_IF_NO_RESULT_TREE();
    }

    annotate_list(items);
    return rval;
  }

  template <Adapter A>
  Status visit(constraint::UniqueItemsConstraint const & cons, A const & document) const {
    NOOP_UNLESS_TYPE(Array);

    if constexpr (std::totally_ordered<A>) {
      // If the adapter defines comparison operators, then it becomes possible
      // to compute uniqueness in O(n*log(n)) checks.
      std::map<A, size_t> cache;
      for (auto const & [index, elem] : detail::enumerate(document.as_array())) {
        if (auto [it, created] = cache.emplace(elem, index); not created) {
          return result(Status::Reject, "items ", it->second, " and ", index, " are equal");
        }
      }
    } else {
      // Otherwise, we need to run an O(n^2) triangular array search comparing
      // equality for each element. This still guarantees that each element is
      // compared against each other element no more than once.
      auto array = document.as_array();
      for (size_t i = 0; i < array.size(); ++i) {
        for (size_t j = i + 1; j < array.size(); ++j) {
          if (array[i].equals(array[j], true)) {
            return result(Status::Reject, "items ", i, " and ", j, " are equal");
          }
        }
      }
    }

    return result(Status::Accept, "all array items are unique");
  }

  Status visit(constraint::AdditionalPropertiesConstraint const & cons,
               Adapter auto const & document) const {
    NOOP_UNLESS_TYPE(Object);

    auto matches_any_pattern = [this, &cons](std::string const & key) {
      return std::ranges::any_of(cons.patterns, [this, &key](auto const & pattern) {
        return regex_.search(pattern, key);
      });
    };

    Status rval = Status::Accept;
    std::vector<std::string> properties;
    for (auto const & [key, elem] : document.as_object()) {
      if (not cons.properties.contains(key) && not matches_any_pattern(key)) {
        VALIDATE_SUBSCHEMA_AND_MARK_LOCAL_VISIT(cons.subschema, elem, key, properties);
      }
      BREAK_EARLY_IF_NO_RESULT_TREE();
    }

    annotate_list(properties);
    return rval;
  }

  Status visit(constraint::DependenciesConstraint const & cons,
               Adapter auto const & document) const {
    NOOP_UNLESS_TYPE(Object);

    auto object = document.as_object();
    Status rval = Status::Accept;
    for (auto const & [key, subschema] : cons.subschemas) {
      if (not object.contains(key)) {
        continue;
      }

      rval &= validate_subschema(subschema, document, key);
      BREAK_EARLY_IF_NO_RESULT_TREE();
    }

    for (auto [key, required] : cons.required) {
      if (not object.contains(key)) {
        continue;
      }

      for (auto const & [key, _] : object) {
        required.erase(key);
      }

      rval &= required.empty();
      BREAK_EARLY_IF_NO_RESULT_TREE();
    }

    return rval;
  }

  Status visit(constraint::MaxPropertiesConstraint const & cons,
               Adapter auto const & document) const {
    NOOP_UNLESS_TYPE(Object);
    if (size_t size = document.object_size(); size > cons.value) {
      return result(Status::Reject, "object of size ", size, " is >", cons.value);
    } else {
      return result(Status::Accept, "object of size ", size, " is <=", cons.value);
    }
  }

  Status visit(constraint::MinPropertiesConstraint const & cons,
               Adapter auto const & document) const {
    NOOP_UNLESS_TYPE(Object);
    if (size_t size = document.object_size(); size < cons.value) {
      return result(Status::Reject, "object of size ", size, " is <", cons.value);
    } else {
      return result(Status::Accept, "object of size ", size, " is >=", cons.value);
    }
  }

  Status visit(constraint::PatternPropertiesConstraint const & cons,
               Adapter auto const & document) const {
    NOOP_UNLESS_TYPE(Object);

    std::vector<std::string> properties;
    Status rval = Status::Accept;
    for (auto const & [pattern, subschema] : cons.properties) {
      for (auto const & [key, elem] : document.as_object()) {
        if (not regex_.search(pattern, key)) {
          continue;
        }
        VALIDATE_SUBSCHEMA_AND_MARK_LOCAL_VISIT(subschema, elem, key, properties);
        BREAK_EARLY_IF_NO_RESULT_TREE();
      }
    }

    annotate_list(properties);
    return rval;
  }

  template <Adapter A>
  Status visit(constraint::PropertiesConstraint const & cons, A const & document) const {
    NOOP_UNLESS_TYPE(Object);

    Status rval = Status::Accept;
    auto object = document.as_object();

    if constexpr (MutableAdapter<A>) {
      // Special Rule - if the adapter is of a mutable json document (wraps a
      // non-const reference and exposes the assign function) we will process
      // the "default" annotation will be applied.
      // https://json-schema.org/draft/2020-12/json-schema-validation#section-9.2
      //
      // Although the JSON Schema draft only says the the default value ought be
      // valid against the schema, this implementation will assure that it is
      // valid against this PropertiesConstraint, and any other constraints that
      // are run after this one.
      for (auto const & [key, subschema] : cons.properties) {
        auto const * default_value = subschema->default_value();
        if (default_value && not object.contains(key)) {
          object.assign(key, *default_value);
        }
      }
    }

    std::vector<std::string> properties;
    for (auto const & [key, elem] : object) {
      if (auto it = cons.properties.find(key); it != cons.properties.end()) {
        VALIDATE_SUBSCHEMA_AND_MARK_LOCAL_VISIT(it->second, elem, key, properties, key);
      }
      BREAK_EARLY_IF_NO_RESULT_TREE();
    }

    annotate_list(properties);
    return rval;
  }

  Status visit(constraint::PropertyNamesConstraint const & cons,
               Adapter auto const & document) const {
    NOOP_UNLESS_TYPE(Object);

    Status rval = Status::Accept;
    for (auto const & [key, _] : document.as_object()) {
      rval &=
          validate_subschema_on(cons.key_schema, detail::StringAdapter(key), std::string("$$key"));
    }
    return rval;
  }

  Status visit(constraint::RequiredConstraint const & cons, Adapter auto const & document) const {
    NOOP_UNLESS_TYPE(Object);

    auto required = cons.properties;
    for (auto const & [key, _] : document.as_object()) {
      required.erase(key);
    }

    if (required.empty()) {
      return result(Status::Accept, "contains all required properties ", cons.properties);
    }

    return result(Status::Reject, "missing required properties ", required);
  }

  Status visit(constraint::UnevaluatedItemsConstraint const & cons,
               Adapter auto const & document) const {
    NOOP_UNLESS_TYPE(Array);
    if (not visited_) {
      return Status::Reject;
    }

    Status rval = Status::Accept;
    std::vector<size_t> items;
    for (auto const & [index, item] : detail::enumerate(document.as_array())) {
      if (not VISITED(size_t).contains(index)) {
        VALIDATE_SUBSCHEMA_AND_MARK_LOCAL_VISIT(cons.subschema, item, index, items);
      }
      BREAK_EARLY_IF_NO_RESULT_TREE();
    }

    annotate_list(items);
    return rval;
  }

  Status visit(constraint::UnevaluatedPropertiesConstraint const & cons,
               Adapter auto const & document) const {
    NOOP_UNLESS_TYPE(Object);
    if (not visited_) {
      return Status::Reject;
    }

    Status rval = Status::Accept;
    std::vector<std::string> properties;
    for (auto const & [key, elem] : document.as_object()) {
      if (not VISITED(std::string).contains(key)) {
        VALIDATE_SUBSCHEMA_AND_MARK_LOCAL_VISIT(cons.subschema, elem, key, properties);
      }
      BREAK_EARLY_IF_NO_RESULT_TREE();
    }

    annotate_list(properties);
    return rval;
  }

public:
  /**
   * @brief The main entry point into the validator. Validates the provided
   * document according to the schema. This function should only be called
   * internally (validate_subschema/validate_subschema_on) or via the Validator
   * class.
   */
  Status validate(Adapter auto const & document) {
    // Step 1) Check if this is an always-false schema. Sometimes, this will
    // have a custom message.
    if (std::optional<std::string> const & reject = schema_->rejects_all()) {
      if (should_annotate(Status::Reject)) {
        // This will only be run if we are interested in why something is
        // rejected. For example - `{ "not": false }` doesn't produce a
        // meaningful annotation...
        result_->error(where_, schema_path_, "", *reject);
      }
      // ...We do always record the result if a result object is present.
      (result_ ? result_->valid(where_, schema_path_, false) : void());
      return Status::Reject;
    }

    if (schema_->accepts_all()) {
      // An accept-all schema is not No-Op for the purpose of unevaluated*
      (result_ ? result_->valid(where_, schema_path_, true) : void());
      return Status::Accept;
    }

    // Begin tracking evaluations for unevaluated* keywords. The annotation
    // object is passed down from parent visitor to child visitor to allow all
    // schemas to mark whether they visited a certain item or property.
    VisitedAnnotation annotate;
    if (schema_->requires_result_context() and not visited_) {
      visited_ = &annotate;
    }

    Status rval = Status::Noop;
    // Before Draft2019_09, reference schemas could not coexist with other
    // constraints. This is enforced in the parsing of the schema, rather than
    // during validation {@see jvalidate::schema::Node::construct}.
    if (std::optional<schema::Node const *> ref = schema_->reference_schema()) {
      // TODO: Investigate why this seems to produce .../$ref/$ref pointers
      rval = validate_subschema(*ref, document, "$ref");
    }

    if (result_ && !schema_->description().empty()) {
      result_->annotate(where_, schema_path_, "description", schema_->description());
    }

    detail::Pointer const current_schema = schema_path_;
    for (auto const & [key, p_constraint] : schema_->constraints()) {
      BREAK_EARLY_IF_NO_RESULT_TREE();
      schema_path_ = current_schema / key;
      rval &= std::visit([this, &document](auto & c) { return this->visit(c, document); },
                         *p_constraint);
    }

    // Post Constraints represent the unevaluatedItems and unevaluatedProperties
    // keywords.
    for (auto const & [key, p_constraint] : schema_->post_constraints()) {
      BREAK_EARLY_IF_NO_RESULT_TREE();
      schema_path_ = current_schema / key;
      rval &= std::visit([this, &document](auto & c) { return this->visit(c, document); },
                         *p_constraint);
    }

    (result_ ? result_->valid(where_, current_schema, static_cast<bool>(rval)) : void());
    return rval;
  }

  // Functions to grant access to some, but not all of the internals of the
  // ValidationVisitor for the purposes of implementing ExtensionVisitor
  // validators.
  detail::Pointer const & where() const { return where_; }
  Root const & root() const { return *root_; }
  ValidationConfig const & config() const { return cfg_; }
  RE & regex() const { return regex_; }

  /**
   * @brief Allow ExtensionVisitor to enter a state similar to a NotConstraint
   * when calling sub-requests.
   *
   * @return A ScopedState object that will restore the tracking mode once it
   * is destroyed.
   */
  [[nodiscard]] detail::ScopedState invert_tracking() const {
    return detail::ScopedState(tracking_, !tracking_);
  }

  /**
   * @brief Allow ExtensionVisitor to enable tracking of all results in child
   * constraints.
   *
   * @return A ScopedState object that will restore the tracking mode once it
   * is destroyed.
   */
  [[nodiscard]] detail::ScopedState track_everything() const {
    return detail::ScopedState(tracking_, StoreResults::ForAnything);
  }

  ANNOTATION_HELPER(error, error, jvalidate::to_string)
  ANNOTATION_HELPER(annotate, annotate, jvalidate::to_string)
  ANNOTATION_HELPER(annotate_list, annotate, jvalidate::to_string_list)

  bool should_annotate(Status stat) const {
    if (not result_) {
      return false;
    }
    switch (*tracking_) {
    case StoreResults::ForAnything:
      return stat != Status::Noop;
    case StoreResults::ForValid:
      return stat == Status::Accept;
    case StoreResults::ForInvalid:
      return stat == Status::Reject;
    }
  }

  Status result(Status stat, auto const &... args) const {
    return (should_annotate(stat) ? error(args...) : void(), stat);
  }

  /**
   * @brief Walking function for entering a subschema.
   *
   * @param subschema The "subschema" being validated. This is either another
   * schema object (jvalidate::schema::Node), or a constraint.
   * @param keys... The path to this subschema, relative to the current schema
   * evaluation.
   *
   * @return The status of validating the current instance against the
   * subschema.
   */
  template <typename... K>
  Status validate_subschema(constraint::SubConstraint const & subschema,
                            Adapter auto const & document, K const &... keys) const {
    if (schema::Node const * const * ppschema = std::get_if<0>(&subschema)) {
      return validate_subschema(*ppschema, document, keys...);
    } else {
      return std::visit([this, &document](auto & c) { return this->visit(c, document); },
                        *std::get<1>(subschema));
    }
  }

  /**
   * @brief Walking function for entering a subschema. Creates a new validation
   * visitor in order to continue evaluation.
   *
   * @param subschema The subschema being validated.
   * @param keys... The path to this subschema, relative to the current schema
   * evaluation.
   *
   * @return The status of validating the current instance against the
   * subschema.
   */
  template <typename... K>
  Status validate_subschema(schema::Node const * subschema, Adapter auto const & document,
                            K const &... keys) const {
    VisitedAnnotation annotate;

    ValidationVisitor next = *this;
    ((next.schema_path_ /= keys), ...);
    std::tie(next.schema_, next.visited_) =
        std::forward_as_tuple(subschema, visited_ ? &annotate : nullptr);

    Status rval = next.validate(document);

    // Only update the visited annotation of the current context if the
    // subschema validates as Accepted.
    if (rval == Status::Accept and visited_) {
      std::get<0>(*visited_).merge(std::get<0>(annotate));
      std::get<1>(*visited_).merge(std::get<1>(annotate));
    }
    return rval;
  }

  /**
   * @brief Walking function for entering a subschema and child document.
   * Creates a new validation visitor in order to continue evaluation.
   *
   * @param subschema The subschema being validated.
   * @param document The child document being evaluated.
   * @param key The path to this document instance.
   * @param schema_keys... The path to this subschema, relative to the current
   * schema evaluation.
   *
   * @return The status of validating the current instance against the
   * subschema.
   */
  template <typename K>
  Status validate_subschema_on(schema::Node const * subschema, Adapter auto const & document,
                               K const & key, auto const &... schema_keys) const {
    ValidationResult result;

    ValidationVisitor next = *this;
    next.where_ /= key;
    ((next.schema_path_ /= schema_keys), ...);
    std::tie(next.schema_, next.result_, next.visited_) =
        std::forward_as_tuple(subschema, result_ ? &result : nullptr, nullptr);

    Status rval = next.validate(document);
    // Only update the visited annotation of the current context if the
    // subschema validates as Accepted.
    if (rval == Status::Accept and visited_) {
      VISITED(K).insert(key);
    }
    // Update the annotation/error content only if a failure is being reported,
    // or if we are in an "if" schema.
    if (should_annotate(rval)) {
      result_->merge(std::move(result));
    }
    return rval;
  }
};
}

#undef ANNOTATION_HELPER
#undef BREAK_EARLY_IF_NO_RESULT_TREE
#undef NOOP_UNLESS_TYPE
#undef VALIDATE_SUBSCHEMA_AND_MARK_LOCAL_VISIT
#undef VISITED