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
struct	sourcemeta::blaze::ValueNone
	Represents a compiler step empty value. More...
struct	sourcemeta::blaze::ValueRegex

Typedefs
using	sourcemeta::blaze::Callback
using	sourcemeta::blaze::Instructions = std::vector<Instruction>
using	sourcemeta::blaze::ValueJSON = sourcemeta::core::JSON
using	sourcemeta::blaze::ValueSet
using	sourcemeta::blaze::ValueString = sourcemeta::core::JSON::String
using	sourcemeta::blaze::ValueProperty
using	sourcemeta::blaze::ValueStrings = std::vector<ValueString>
using	sourcemeta::blaze::ValueStringSet = sourcemeta::core::JSONPropertySet
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::ValueStringMap
using	sourcemeta::blaze::ValuePropertyFilter
using	sourcemeta::blaze::ValueIndexPair = std::pair<std::size_t, std::size_t>
using	sourcemeta::blaze::ValuePointer = sourcemeta::core::Pointer
using	sourcemeta::blaze::ValueNamedIndex
using	sourcemeta::blaze::ValueNamedIndexes
using	sourcemeta::blaze::ValueTypedProperties = std::pair<ValueType, ValueStringSet>
using	sourcemeta::blaze::ValueStringHashes
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::ValueTypesWithSize = std::pair<ValueTypes, ValueRange>
using	sourcemeta::blaze::ValueObjectProperties
using	sourcemeta::blaze::Value

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 ,   AssertionNumberIntegerBounded , AssertionNumberType , AssertionStringType , AssertionPropertyType ,   AssertionPropertyTypeEvaluate , AssertionPropertyTypeStrict , AssertionPropertyTypeStrictEvaluate , AssertionPropertyTypeStrictAny ,   AssertionPropertyTypeStrictAnyEvaluate , AssertionPropertyEqual , AssertionArrayPrefix , AssertionArrayPrefixEvaluate ,   AssertionObjectPropertiesSimple , AnnotationEmit , AnnotationEmitWrapped , 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 ,   LoopItemsArrayBoundedTypeStrictAny , 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 , Base64 }
enum class	sourcemeta::blaze::ValueNumberType : std::uint8_t { Float , Double }

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::is_wrapped_annotation (const InstructionIndex type) noexcept -> bool
auto	sourcemeta::blaze::describe (const Template &schema_template, 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 {15}
constexpr std::string_view	sourcemeta::blaze::INSTRUCTION_NAMES []

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
std::vector< std::string >	vocabularies
	The vocabulary URIs that instructions refer to, without duplicates.
std::vector< std::string >	messages
	The message templates that instructions refer to, without duplicates.

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/core/jsonschema.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::core::schema_walker,
    sourcemeta::core::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/core/jsonpointer.h>
#include <sourcemeta/core/jsonschema.h>
 
#include <cassert>
#include <cstddef>
#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::core::schema_walker,
    sourcemeta::core::schema_resolver,
    sourcemeta::blaze::default_schema_compiler)};
 
static auto callback(
    const sourcemeta::blaze::EvaluationType type,
    const bool result,
    const sourcemeta::blaze::Instruction &instruction,
    const sourcemeta::blaze::InstructionExtra &extra,
    const sourcemeta::core::WeakPointer &evaluate_path,
    const sourcemeta::core::WeakPointer &instance_location,
    const sourcemeta::core::JSON &annotation) -> void {
  if (type == sourcemeta::blaze::EvaluationType::Pre) {
    return;
  }
 
  std::cout << "RESULT: " << (result ? "Success" : "Failure") << "\n";
  std::cout << "INSTRUCTION: "
            << sourcemeta::blaze::InstructionNames[
                 static_cast<std::size_t>(instruction.type)]
            << "\n";
  std::cout << "KEYWORD LOCATION: " << extra.keyword_location << "\n";
  std::cout << "EVALUATE PATH: ";
  sourcemeta::core::stringify(evaluate_path, std::cout);
  std::cout << "\nINSTANCE LOCATION: ";
  sourcemeta::core::stringify(instance_location, std::cout);
  std::cout << "\nANNOTATION: ";
  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
std::size_t	vocabulary
std::size_t	message
std::size_t	message_detail

Member Data Documentation

message

std::size_t sourcemeta::blaze::InstructionExtra::message

A one-based index into Template::messages, where zero means the instruction has no message template of its own

message_detail

std::size_t sourcemeta::blaze::InstructionExtra::message_detail

The template to render instead when the instruction has something of its own to report, such as which properties were missing. Zero when the instruction says the same thing either way

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::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

Initial value:

 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 = std::vector<Instruction>

Represents a set of schema compilation steps that can be evaluated

Value

using sourcemeta::blaze::Value

Initial 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, ValueNumberType, ValueTypesWithSize>

ValueBoolean

using sourcemeta::blaze::ValueBoolean = bool

Represents a compiler step boolean value

ValueIndexPair

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

Represents a compiler step value that consists of two indexes

ValueIntegerBounds

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

Represents integer bounds with minimum and maximum

ValueIntegerBoundsWithSize

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

Represents integer bounds combined with array size range

ValueJSON

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

Represents a compiler step JSON value

ValueNamedIndex

using sourcemeta::blaze::ValueNamedIndex

Initial value:

 std::tuple<sourcemeta::core::JSON::Object::hash_type,
                                   ValueUnsignedInteger, ValueString>

Represents the precomputed hash of a property name, the index of the child instruction that applies to it, and the name itself. The hash comes first as it is what a lookup compares against

ValueNamedIndexes

using sourcemeta::blaze::ValueNamedIndexes

Initial value:

 
    std::pair<std::vector<ValueNamedIndex>, std::vector<ValueIndexPair>>

Represents a compiler step string to index map. The entries are sorted by the size of the name, and the table of contents gives, for every name size, the one-based inclusive range of entries that have that size, so that a lookup only ever compares the names whose size can match

ValueObjectProperties

using sourcemeta::blaze::ValueObjectProperties

Initial value:

 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 = sourcemeta::core::Pointer

Represents a compiler step value that consists of a pointer

ValueProperty

using sourcemeta::blaze::ValueProperty

Initial value:

 
    std::pair<ValueString, sourcemeta::core::JSON::Object::hash_type>

Represents a compiler step object property value

ValuePropertyFilter

using sourcemeta::blaze::ValuePropertyFilter

Initial value:

 
    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 = 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

Initial value:

 
    std::unordered_set<sourcemeta::core::JSON,
                       sourcemeta::core::HashJSON<sourcemeta::core::JSON>>

Represents a set of JSON values

ValueString

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

Represents a compiler step string value

ValueStringHashes

using sourcemeta::blaze::ValueStringHashes

Initial value:

 
    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

Initial value:

 sourcemeta::core::JSONObject<
    ValueString, ValueStrings, sourcemeta::core::PropertyHashJSON<ValueString>>

Represents an compiler step that maps strings to strings

ValueStrings

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

Represents a compiler step string values

ValueStringSet

using sourcemeta::blaze::ValueStringSet = sourcemeta::core::JSONPropertySet

Represents a compiler step string set of values

ValueType

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

Represents a compiler step JSON type value

ValueTypedHashes

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

Represents a compiler step types property hashes value

ValueTypedProperties

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

Represents a compiler step types properties value

ValueTypes

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

Represents a compiler step JSON types value as a bitmask

ValueTypesWithSize

using sourcemeta::blaze::ValueTypesWithSize = std::pair<ValueTypes, ValueRange>

Represents a set of types combined with an array size range

ValueUnsignedInteger

using sourcemeta::blaze::ValueUnsignedInteger = 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.

ValueNumberType

enum class sourcemeta::blaze::ValueNumberType : std::uint8_t

strong

Represents a compiler step number logical type

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 Template &	schema_template,
		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

is_wrapped_annotation()

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

inlinenoexcept

Check if a given instruction type corresponds to a wrapped annotation