schema.hpp

Go to the documentation of this file.

#pragma once
 
/// @file userver/formats/json/schema.hpp
/// @brief JSON schema validator
 
#include <string>
#include <string_view>
 
#include <userver/formats/json/exception.hpp>
#include <userver/formats/json/value.hpp>
#include <userver/utils/fast_pimpl.hpp>
 
USERVER_NAMESPACE_BEGIN
 
namespace formats::json {
 
/// @see formats::json::Schema::ValidationError::Throw
class SchemaValidationException final : public ExceptionWithPath {
public:
    SchemaValidationException(std::string_view msg, std::string_view path, std::string_view schema_path);
 
    std::string_view GetSchemaPath() const noexcept;
 
private:
    std::string schema_path_;
};
 
/// @brief Contains a prepared JSON schema.
///
/// Usage example:
/// @snippet formats/json/schema_test.cpp  sample
class Schema final {
public:
    class ValidationResult;
    class ValidationError;
 
    explicit Schema(const Value& doc);
    ~Schema() noexcept;
 
    /// @brief Validates JSON against the Schema.
    /// @returns ValidationResult describing the validation error, if any.
    ValidationResult Validate(const Value& doc) const;
 
private:
    struct Impl;
    static constexpr std::size_t kSize = 288;
    static constexpr std::size_t kAlignment = 8;
    utils::FastPimpl<Impl, kSize, kAlignment> impl_;
};
 
/// Contains error details (if any) from Schema::Validate.
class Schema::ValidationResult final {
public:
    /// Creates an `IsValid` result.
    ValidationResult() noexcept;
 
    ValidationResult(ValidationResult&&) noexcept;
    ValidationResult& operator=(ValidationResult&&) noexcept;
    ~ValidationResult() noexcept;
 
    /// @returns `true` on validation success.
    explicit operator bool() const noexcept;
 
    /// @returns `true` on validation success.
    bool IsValid() const noexcept;
 
    /// @returns `true` on validation error.
    bool IsError() const noexcept;
 
    /// @throws SchemaValidationException on validation error.
    /// @see Schema::ValidationResult::GetError
    /// @see Schema::ValidationError::Throw
    void ThrowIfError() &&;
 
    /// @returns Validation error, `IsError` must be true.
    ValidationError GetError() &&;
 
private:
    friend class Schema;
    friend class ValidationError;
 
    struct Impl;
    static constexpr std::size_t kSize = 24;
    static constexpr std::size_t kAlignment = 8;
    utils::FastPimpl<Impl, kSize, kAlignment> impl_;
};
 
class Schema::ValidationError final {
public:
    /// @throws SchemaValidationException with error details.
    /// @see Schema::ValidationResult::ThrowIfError
    [[noreturn]] void Throw() const;
 
    /// Describes the location within the validated JSON which violates
    /// schema. The exact format of value path is unstable and should not
    /// be relied upon.
    std::string_view GetValuePath() const;
    /// Describes the location within the schema which was violated. The exact
    /// format of schema path is unstable and should not be relied upon.
    std::string_view GetSchemaPath() const;
    /// Describes the specifics of what condition was violated. The exact
    /// format of details is unstable and should not be relied upon.
    std::string_view GetDetailsString() const;
 
private:
    friend class ValidationResult;
 
    ValidationError();
 
    std::string value_path_;
    std::string schema_path_;
    std::string details_string_;
};
 
}  // namespace formats::json
 
USERVER_NAMESPACE_END