Evaluator

A high-performance JSON Schema evaluator. More...

Classes
struct	sourcemeta::blaze::Template
class	sourcemeta::blaze::Evaluator
class	sourcemeta::blaze::EvaluationError
struct	sourcemeta::blaze::InstructionExtra
struct	sourcemeta::blaze::Instruction
class	sourcemeta::blaze::StringSet
struct	sourcemeta::blaze::ValueNone
	Represents a compiler step empty value. More...
struct	sourcemeta::blaze::ValueRegex

Typedefs
using	sourcemeta::blaze::Callback = std::function< void(const EvaluationType, bool, const Instruction &, const InstructionExtra &, const sourcemeta::core::WeakPointer &, const sourcemeta::core::WeakPointer &, const sourcemeta::core::JSON &)>
using	sourcemeta::blaze::Instructions = std::vector< Instruction >
using	sourcemeta::blaze::ValueJSON = sourcemeta::core::JSON
using	sourcemeta::blaze::ValueSet = std::unordered_set< sourcemeta::core::JSON, sourcemeta::core::HashJSON< sourcemeta::core::JSON > >
using	sourcemeta::blaze::ValueString = sourcemeta::core::JSON::String
using	sourcemeta::blaze::ValueProperty = std::pair< ValueString, sourcemeta::core::JSON::Object::hash_type >
using	sourcemeta::blaze::ValueStrings = std::vector< ValueString >
using	sourcemeta::blaze::ValueStringSet = StringSet
using	sourcemeta::blaze::ValueTypes = sourcemeta::core::JSON::TypeSet
using	sourcemeta::blaze::ValueType = sourcemeta::core::JSON::Type
using	sourcemeta::blaze::ValueUnsignedInteger = std::size_t
using	sourcemeta::blaze::ValueRange = std::tuple< std::size_t, std::optional< std::size_t >, bool >
using	sourcemeta::blaze::ValueBoolean = bool
using	sourcemeta::blaze::ValueNamedIndexes = sourcemeta::core::JSONObject< ValueString, ValueUnsignedInteger, sourcemeta::core::PropertyHashJSON< ValueString > >
using	sourcemeta::blaze::ValueStringMap = sourcemeta::core::JSONObject< ValueString, ValueStrings, sourcemeta::core::PropertyHashJSON< ValueString > >
using	sourcemeta::blaze::ValuePropertyFilter = std::tuple< ValueStringSet, ValueStrings, std::vector< ValueRegex > >
using	sourcemeta::blaze::ValueIndexPair = std::pair< std::size_t, std::size_t >
using	sourcemeta::blaze::ValuePointer = sourcemeta::core::Pointer
using	sourcemeta::blaze::ValueTypedProperties = std::pair< ValueType, ValueStringSet >
using	sourcemeta::blaze::ValueStringHashes = std::pair< std::vector< std::pair< ValueStringSet::hash_type, ValueString > >, std::vector< ValueIndexPair > >
using	sourcemeta::blaze::ValueTypedHashes = std::pair< ValueType, ValueStringHashes >
using	sourcemeta::blaze::ValueIntegerBounds = std::pair< std::int64_t, std::int64_t >
using	sourcemeta::blaze::ValueIntegerBoundsWithSize = std::pair< ValueIntegerBounds, ValueRange >
using	sourcemeta::blaze::ValueObjectProperties = std::vector< std::tuple< ValueString, sourcemeta::core::JSON::Object::hash_type, bool > >
using	sourcemeta::blaze::Value = std::variant< ValueNone, ValueJSON, ValueSet, ValueString, ValueProperty, ValueStrings, ValueStringSet, ValueTypes, ValueType, ValueRegex, ValueUnsignedInteger, ValueRange, ValueBoolean, ValueNamedIndexes, ValueStringType, ValueStringMap, ValuePropertyFilter, ValueIndexPair, ValuePointer, ValueTypedProperties, ValueStringHashes, ValueTypedHashes, ValueIntegerBounds, ValueIntegerBoundsWithSize, ValueObjectProperties >

Enumerations
enum class	sourcemeta::blaze::Mode : std::uint8_t { Mode::FastValidation , Mode::Exhaustive }
enum class	sourcemeta::blaze::EvaluationType : std::uint8_t { Pre , Post }
enum class	InstructionIndex : std::uint8_t {   AssertionFail = 0 , AssertionDefines , AssertionDefinesStrict , AssertionDefinesAll ,   AssertionDefinesAllStrict , AssertionDefinesExactly , AssertionDefinesExactlyStrict , AssertionDefinesExactlyStrictHash3 ,   AssertionPropertyDependencies , AssertionType , AssertionTypeAny , AssertionTypeStrict ,   AssertionTypeStrictAny , AssertionNotTypeStrictAny , AssertionTypeStringBounded , AssertionTypeStringUpper ,   AssertionTypeArrayBounded , AssertionTypeArrayUpper , AssertionTypeObjectBounded , AssertionTypeObjectUpper ,   AssertionRegex , AssertionStringSizeLess , AssertionStringSizeGreater , AssertionArraySizeLess ,   AssertionArraySizeGreater , AssertionObjectSizeLess , AssertionObjectSizeGreater , AssertionEqual ,   AssertionEqualsAny , AssertionEqualsAnyStringHash , AssertionGreaterEqual , AssertionLessEqual ,   AssertionGreater , AssertionLess , AssertionUnique , AssertionDivisible ,   AssertionTypeIntegerBounded , AssertionTypeIntegerBoundedStrict , AssertionTypeIntegerLowerBound , AssertionTypeIntegerLowerBoundStrict ,   AssertionStringType , AssertionPropertyType , AssertionPropertyTypeEvaluate , AssertionPropertyTypeStrict ,   AssertionPropertyTypeStrictEvaluate , AssertionPropertyTypeStrictAny , AssertionPropertyTypeStrictAnyEvaluate , AssertionArrayPrefix ,   AssertionArrayPrefixEvaluate , AssertionObjectPropertiesSimple , AnnotationEmit , AnnotationToParent ,   AnnotationBasenameToParent , Evaluate , LogicalNot , LogicalNotEvaluate ,   LogicalOr , LogicalAnd , LogicalXor , LogicalCondition ,   LogicalWhenType , LogicalWhenDefines , LogicalWhenArraySizeGreater , LoopPropertiesUnevaluated ,   LoopPropertiesUnevaluatedExcept , LoopPropertiesMatch , LoopPropertiesMatchClosed , LoopProperties ,   LoopPropertiesEvaluate , LoopPropertiesRegex , LoopPropertiesRegexClosed , LoopPropertiesStartsWith ,   LoopPropertiesExcept , LoopPropertiesType , LoopPropertiesTypeEvaluate , LoopPropertiesExactlyTypeStrict ,   LoopPropertiesExactlyTypeStrictHash , LoopPropertiesTypeStrict , LoopPropertiesTypeStrictEvaluate , LoopPropertiesTypeStrictAny ,   LoopPropertiesTypeStrictAnyEvaluate , LoopKeys , LoopItems , LoopItemsFrom ,   LoopItemsUnevaluated , LoopItemsType , LoopItemsTypeStrict , LoopItemsTypeStrictAny ,   LoopItemsPropertiesExactlyTypeStrictHash , LoopItemsPropertiesExactlyTypeStrictHash3 , LoopItemsIntegerBounded , LoopItemsIntegerBoundedSized ,   LoopContains , ControlGroup , ControlGroupWhenDefines , ControlGroupWhenDefinesDirect ,   ControlGroupWhenType , ControlEvaluate , ControlDynamicAnchorJump , ControlJump }
enum class	sourcemeta::blaze::ValueStringType : std::uint8_t {   URI , URIReference , URITemplate , IRI ,   IRIReference , Email , IDNEmail , IPv4 ,   IPv6 , Hostname , IDNHostname , DateTime ,   Date , Time , PartialTime , Duration ,   JSONPointer , RelativeJSONPointer , UUID , Regex ,   Color }

Functions
auto	sourcemeta::blaze::from_json (const sourcemeta::core::JSON &json) -> std::optional< Template >
auto	sourcemeta::blaze::is_annotation (const InstructionIndex type) noexcept -> bool
auto	sourcemeta::blaze::describe (const bool valid, const Instruction &step, const sourcemeta::core::WeakPointer &evaluate_path, const sourcemeta::core::WeakPointer &instance_location, const sourcemeta::core::JSON &instance, const sourcemeta::core::JSON &annotation) -> std::string

Variables
constexpr std::size_t	sourcemeta::blaze::JSON_VERSION {5}
constexpr std::string_view	sourcemeta::blaze::InstructionNames []

Detailed Description

A high-performance JSON Schema evaluator.

This functionality is included as follows:

#include <sourcemeta/blaze/evaluator.h>

---

Class Documentation

sourcemeta::blaze::Template

struct sourcemeta::blaze::Template

Represents a compiled schema ready for execution

Public Attributes
bool	dynamic
bool	track
std::vector< Instructions >	targets
std::vector< std::pair< std::size_t, std::size_t > >	labels
std::vector< InstructionExtra >	extra

sourcemeta::blaze::Evaluator

class sourcemeta::blaze::Evaluator

Public Member Functions
auto	validate (const Template &schema, const sourcemeta::core::JSON &instance) -> bool
auto	validate (const Template &schema, const sourcemeta::core::JSON &instance, const Callback &callback) -> bool

Member Function Documentation

validate() [1/2]

auto sourcemeta::blaze::Evaluator::validate ( const Template &  schema, const sourcemeta::core::JSON &  instance  ) -> bool

inline

This function evaluates a schema compiler template, returning a boolean without error information. For example:

#include <sourcemeta/blaze/evaluator.h>
#include <sourcemeta/blaze/compiler.h>
 
#include <sourcemeta/core/json.h>
#include <sourcemeta/blaze/foundation.h>
 
#include <cassert>
 
const sourcemeta::core::JSON schema =
    sourcemeta::core::parse_json(R"JSON({
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "string"
})JSON");
 
const auto schema_template{sourcemeta::blaze::compile(
    schema, sourcemeta::blaze::schema_walker,
    sourcemeta::blaze::schema_resolver,
    sourcemeta::blaze::default_schema_compiler)};
 
sourcemeta::blaze::Evaluator evaluator;
const sourcemeta::core::JSON instance{"foo bar"};
const auto result{evaluator.validate(schema_template, instance)};
assert(result);

validate() [2/2]

auto sourcemeta::blaze::Evaluator::validate ( const Template &  schema, const sourcemeta::core::JSON &  instance, const Callback &  callback  ) -> bool

inline

This method evaluates a schema compiler template, executing the given callback at every step of the way. For example:

#include <sourcemeta/blaze/evaluator.h>
#include <sourcemeta/blaze/compiler.h>
 
#include <sourcemeta/core/json.h>
#include <sourcemeta/blaze/foundation.h>
 
#include <cassert>
#include <iostream>
 
const sourcemeta::core::JSON schema =
    sourcemeta::core::parse_json(R"JSON({
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "string"
})JSON");
 
const auto schema_template{sourcemeta::blaze::compile(
    schema, sourcemeta::blaze::schema_walker,
    sourcemeta::blaze::schema_resolver,
    sourcemeta::blaze::default_schema_compiler)};
 
static auto callback(
    bool result,
    const sourcemeta::blaze::Instruction &instruction,
    const sourcemeta::core::Pointer &evaluate_path,
    const sourcemeta::core::Pointer &instance_location,
    const sourcemeta::core::JSON &document,
    const sourcemeta::core::JSON &annotation) -> void {
  std::cout << "TYPE: " << (result ? "Success" : "Failure") << "\n";
  std::cout << "INSTRUCTION:\n";
  sourcemeta::core::prettify(sourcemeta::blaze::to_json({instruction}),
                                    std::cout);
  std::cout << "\nEVALUATE PATH:";
  sourcemeta::core::stringify(evaluate_path, std::cout);
  std::cout << "\nINSTANCE LOCATION:";
  sourcemeta::core::stringify(instance_location, std::cout);
  std::cout << "\nANNOTATION:\n";
  sourcemeta::core::prettify(annotation, std::cout);
  std::cout << "\n";
}
 
sourcemeta::blaze::Evaluator evaluator;
const sourcemeta::core::JSON instance{"foo bar"};
const auto result{evaluator.validate(
  schema_template, instance, callback)};
 
assert(result);

sourcemeta::blaze::EvaluationError

class sourcemeta::blaze::EvaluationError

An error that represents a schema evaluation error event

Inheritance diagram for sourcemeta::blaze::EvaluationError:

Public Member Functions
	EvaluationError (const char *message)
	EvaluationError (std::string message)=delete
	EvaluationError (std::string &&message)=delete
	EvaluationError (std::string_view message)=delete
auto	what () const noexcept -> const char *override

sourcemeta::blaze::InstructionExtra

struct sourcemeta::blaze::InstructionExtra

Satellite data for an instruction that is not needed during fast evaluation

Public Attributes
sourcemeta::core::Pointer	relative_schema_location
std::string	keyword_location
std::size_t	schema_resource

sourcemeta::blaze::Instruction

struct sourcemeta::blaze::Instruction

Represents a single instruction to be evaluated

Public Attributes
InstructionIndex	type
sourcemeta::core::Pointer	relative_instance_location
Value	value
Instructions	children
std::size_t	extra_index

sourcemeta::blaze::StringSet

class sourcemeta::blaze::StringSet

Public Types
using	string_type = sourcemeta::core::JSON::String
using	hash_type = sourcemeta::core::JSON::Object::hash_type
using	value_type = std::pair< string_type, hash_type >
using	underlying_type = std::vector< value_type >
using	size_type = typename underlying_type::size_type
using	difference_type = typename underlying_type::difference_type
using	const_iterator = typename underlying_type::const_iterator
Public Member Functions
auto	contains (const string_type &value, const hash_type hash) const -> bool
auto	contains (const string_type &value) const -> bool
auto	at (const size_type index) const noexcept -> const value_type &
auto	insert (const string_type &value) -> void
auto	insert (string_type &&value) -> void
auto	empty () const noexcept -> bool
auto	size () const noexcept -> size_type
auto	begin () const -> const_iterator
auto	end () const -> const_iterator
auto	cbegin () const -> const_iterator
auto	cend () const -> const_iterator
auto	to_json () const -> sourcemeta::core::JSON
Static Public Member Functions
static auto	from_json (const sourcemeta::core::JSON &value) -> std::optional< StringSet >

sourcemeta::blaze::ValueNone

struct sourcemeta::blaze::ValueNone

Represents a compiler step empty value.

Public Member Functions
auto	to_json () const -> sourcemeta::core::JSON
Static Public Member Functions
static auto	from_json (const sourcemeta::core::JSON &) -> std::optional< ValueNone >

sourcemeta::blaze::ValueRegex

struct sourcemeta::blaze::ValueRegex

Represents a compiler step ECMA regular expression value. We store both the original string and the regular expression as standard regular expressions do not keep a copy of their original value (which we need for serialization purposes)

Public Types
using	second_type = ValueString
using	first_type = sourcemeta::core::Regex
Public Member Functions
auto	to_json () const -> sourcemeta::core::JSON
Static Public Member Functions
static auto	from_json (const sourcemeta::core::JSON &value) -> std::optional< ValueRegex >
Public Attributes
first_type	first
second_type	second

Typedef Documentation

Callback

using sourcemeta::blaze::Callback = typedef std::function<void( const EvaluationType, bool, const Instruction &, const InstructionExtra &, const sourcemeta::core::WeakPointer &, const sourcemeta::core::WeakPointer &, const sourcemeta::core::JSON &)>

A callback of this type is invoked after evaluating any keyword. The arguments go as follows:

• The stage at which the instruction in question is
• Whether the evaluation was successful or not (always true before evaluation)
• The instruction that was just evaluated
• The extra data associated with the instruction
• The evaluation path
• The instance location
• The annotation result, if any (otherwise null)

You can use this callback mechanism to implement arbitrary output formats.

Instructions

using sourcemeta::blaze::Instructions = typedef std::vector<Instruction>

Represents a set of schema compilation steps that can be evaluated

ValueBoolean

using sourcemeta::blaze::ValueBoolean = typedef bool

Represents a compiler step boolean value

ValueIndexPair

using sourcemeta::blaze::ValueIndexPair = typedef std::pair<std::size_t, std::size_t>

Represents a compiler step value that consists of two indexes

ValueIntegerBounds

using sourcemeta::blaze::ValueIntegerBounds = typedef std::pair<std::int64_t, std::int64_t>

Represents integer bounds with minimum and maximum

ValueIntegerBoundsWithSize

using sourcemeta::blaze::ValueIntegerBoundsWithSize = typedef std::pair<ValueIntegerBounds, ValueRange>

Represents integer bounds combined with array size range

ValueJSON

using sourcemeta::blaze::ValueJSON = typedef sourcemeta::core::JSON

Represents a compiler step JSON value

ValueNamedIndexes

using sourcemeta::blaze::ValueNamedIndexes = typedef sourcemeta::core::JSONObject< ValueString, ValueUnsignedInteger, sourcemeta::core::PropertyHashJSON<ValueString> >

Represents a compiler step string to index map

ValueObjectProperties

using sourcemeta::blaze::ValueObjectProperties = typedef std::vector< std::tuple<ValueString, sourcemeta::core::JSON::Object::hash_type, bool> >

Represents a list of object property entries: (name, hash, required)

ValuePointer

using sourcemeta::blaze::ValuePointer = typedef sourcemeta::core::Pointer

Represents a compiler step value that consists of a pointer

ValueProperty

using sourcemeta::blaze::ValueProperty = typedef std::pair<ValueString, sourcemeta::core::JSON::Object::hash_type>

Represents a compiler step object property value

ValuePropertyFilter

using sourcemeta::blaze::ValuePropertyFilter = typedef std::tuple<ValueStringSet, ValueStrings, std::vector<ValueRegex> >

Represents a compiler step value that consist of object property filters (strings, prefixes, regexes)

ValueRange

using sourcemeta::blaze::ValueRange = typedef std::tuple<std::size_t, std::optional<std::size_t>, bool>

Represents a compiler step range value. The boolean option modifies whether the range is considered exhaustively or if the evaluator is allowed to break early

ValueSet

using sourcemeta::blaze::ValueSet = typedef std::unordered_set<sourcemeta::core::JSON, sourcemeta::core::HashJSON<sourcemeta::core::JSON> >

Represents a set of JSON values

ValueString

using sourcemeta::blaze::ValueString = typedef sourcemeta::core::JSON::String

Represents a compiler step string value

ValueStringHashes

using sourcemeta::blaze::ValueStringHashes = typedef std::pair<std::vector<std::pair<ValueStringSet::hash_type, ValueString> >, std::vector<ValueIndexPair> >

Represents a compiler step types property hashes value

ValueStringMap

using sourcemeta::blaze::ValueStringMap = typedef sourcemeta::core::JSONObject< ValueString, ValueStrings, sourcemeta::core::PropertyHashJSON<ValueString> >

Represents an compiler step that maps strings to strings

ValueStrings

using sourcemeta::blaze::ValueStrings = typedef std::vector<ValueString>

Represents a compiler step string values

ValueStringSet

using sourcemeta::blaze::ValueStringSet = typedef StringSet

Represents a compiler step string set of values

ValueType

using sourcemeta::blaze::ValueType = typedef sourcemeta::core::JSON::Type

Represents a compiler step JSON type value

ValueTypedHashes

using sourcemeta::blaze::ValueTypedHashes = typedef std::pair<ValueType, ValueStringHashes>

Represents a compiler step types property hashes value

ValueTypedProperties

using sourcemeta::blaze::ValueTypedProperties = typedef std::pair<ValueType, ValueStringSet>

Represents a compiler step types properties value

ValueTypes

using sourcemeta::blaze::ValueTypes = typedef sourcemeta::core::JSON::TypeSet

Represents a compiler step JSON types value as a bitmask

ValueUnsignedInteger

using sourcemeta::blaze::ValueUnsignedInteger = typedef std::size_t

Represents a compiler step JSON unsigned integer value

Enumeration Type Documentation

EvaluationType

enum class sourcemeta::blaze::EvaluationType : std::uint8_t

strong

Represents the state of an instruction evaluation

Mode

enum class sourcemeta::blaze::Mode : std::uint8_t

strong

Represents the mode of compilation

Enumerator
FastValidation	Attempt to get to a boolean result as fast as possible.
Exhaustive	Perform exhaustive evaluation, including annotations.

ValueStringType

enum class sourcemeta::blaze::ValueStringType : std::uint8_t

strong

Represents a compiler step string logical type

Function Documentation

describe()

auto sourcemeta::blaze::describe	(	const bool	valid,
		const Instruction &	step,
		const sourcemeta::core::WeakPointer &	evaluate_path,
		const sourcemeta::core::WeakPointer &	instance_location,
		const sourcemeta::core::JSON &	instance,
		const sourcemeta::core::JSON &	annotation
	)		-> std::string

This function translates a "post" step execution into a human-readable string. Useful as the building block for producing user-friendly evaluation results.

Note that describing a "pre" step execution is NOT supported.

from_json()

auto sourcemeta::blaze::from_json

(

const sourcemeta::core::JSON &

json

)

-> std::optional< Template >

Parse a template from JSON

is_annotation()

auto sourcemeta::blaze::is_annotation ( const InstructionIndex  type ) -> bool

inlinenoexcept

Check if a given instruction type corresponds to an annotation