Compiler

Compile a JSON Schema into a set of low-level instructions for fast evaluation. More...

Classes
struct	sourcemeta::blaze::SchemaUnevaluatedEntry
struct	sourcemeta::blaze::SchemaContext
struct	sourcemeta::blaze::DynamicContext
class	sourcemeta::blaze::InstructionExtras
struct	sourcemeta::blaze::Tweaks
struct	sourcemeta::blaze::Context
struct	sourcemeta::blaze::KeywordContext
class	sourcemeta::blaze::CompilerError
class	sourcemeta::blaze::CompilerInvalidRegexError
class	sourcemeta::blaze::CompilerReferenceTargetNotSchemaError
class	sourcemeta::blaze::CompilerInstructionLimitError
class	sourcemeta::blaze::CompilerDepthLimitError
class	sourcemeta::blaze::CompilerInvalidEntryPoint

Typedefs
using	sourcemeta::blaze::SchemaUnevaluatedEntries
using	sourcemeta::blaze::Compiler

Functions
auto	sourcemeta::blaze::default_schema_compiler (const KeywordContext &, const Instructions &) -> Instructions
auto	sourcemeta::blaze::compile (const sourcemeta::core::JSON &schema, const sourcemeta::core::SchemaWalker &walker, const sourcemeta::core::SchemaResolver &resolver, const Compiler &compiler, const Mode mode=Mode::FastValidation, const std::string_view default_dialect="", const std::string_view default_id="", const std::string_view entrypoint="", const std::optional< Tweaks > &tweaks=std::nullopt, std::uint64_t max_locations=std::numeric_limits< std::uint64_t >::max()) -> Template
auto	sourcemeta::blaze::compile (const sourcemeta::core::JSON &schema, const sourcemeta::core::SchemaWalker &walker, const sourcemeta::core::SchemaResolver &resolver, const Compiler &compiler, const sourcemeta::core::SchemaFrame &frame, const std::string_view entrypoint, const Mode mode=Mode::FastValidation, const std::optional< Tweaks > &tweaks=std::nullopt) -> Template
auto	sourcemeta::blaze::compile (const KeywordContext &context, const sourcemeta::core::WeakPointer &schema_suffix, const sourcemeta::core::WeakPointer &instance_suffix=sourcemeta::core::EMPTY_WEAK_POINTER, std::optional< std::string_view > uri=std::nullopt) -> Instructions
auto	sourcemeta::blaze::to_json (const Template &schema_template) -> sourcemeta::core::JSON

Variables
const sourcemeta::core::JSON::String	sourcemeta::blaze::EMPTY_KEYWORD

Detailed Description

Compile a JSON Schema into a set of low-level instructions for fast evaluation.

---

Class Documentation

sourcemeta::blaze::SchemaUnevaluatedEntry

struct sourcemeta::blaze::SchemaUnevaluatedEntry

Public Attributes
std::set< sourcemeta::core::WeakPointer >	static_dependencies
	The absolute pointers of the static keyword dependencies.
std::set< sourcemeta::core::WeakPointer >	dynamic_dependencies
bool	unresolved {false}

Member Data Documentation

dynamic_dependencies

std::set<sourcemeta::core::WeakPointer> sourcemeta::blaze::SchemaUnevaluatedEntry::dynamic_dependencies

The absolute pointers of the dynamic keyword dependencies, along with the references that lead to them

unresolved

bool sourcemeta::blaze::SchemaUnevaluatedEntry::unresolved {false}

Whether the entry cannot be fully resolved, which means there might be unknown dynamic dependencies

sourcemeta::blaze::SchemaContext

struct sourcemeta::blaze::SchemaContext

The schema compiler context is the current subschema information you have at your disposal to implement a keyword

Public Attributes
const sourcemeta::core::WeakPointer &	relative_pointer
	The schema location relative to the base URI.
const sourcemeta::core::JSON &	schema
	The current subschema.
const sourcemeta::core::SchemaVocabularies &	vocabularies
	The schema vocabularies in use.
const sourcemeta::core::URI &	base
	The schema base URI.
bool	is_property_name
	Whether the current schema targets a property name.

sourcemeta::blaze::DynamicContext

struct sourcemeta::blaze::DynamicContext

The dynamic compiler context is the read-write information you have at your disposal to implement a keyword

Public Member Functions
auto	value () const -> const sourcemeta::core::JSON &
Public Attributes
const sourcemeta::core::JSON::String &	keyword
	The schema keyword.
const sourcemeta::core::JSON *	keyword_value {nullptr}
	The value of the keyword, null in a context that names none.
const sourcemeta::core::WeakPointer &	base_schema_location
	The schema base keyword path.
const sourcemeta::core::WeakPointer &	base_instance_location
	The base instance location that the keyword must be evaluated to.

Member Function Documentation

value()

auto sourcemeta::blaze::DynamicContext::value ( ) const->constsourcemeta::core::JSON &

inlinenodiscard

What the keyword this context names is set to. Only a context built to compile a keyword carries one

sourcemeta::blaze::InstructionExtras

class sourcemeta::blaze::InstructionExtras

An accumulator for instruction metadata that refuses to grow past a limit. Compilation makes one entry here for every instruction it makes, including the ones it goes on to throw away and the copies that inlining leaves behind, so what this holds is what compiling the schema cost

Public Member Functions
	InstructionExtras (const std::uint64_t limit)
auto	push_back (InstructionExtra &&entry) -> void
	Make room for another instruction, throwing once out of room.
auto	size () const noexcept -> std::size_t
auto	operator[] (const std::size_t index) const noexcept -> const InstructionExtra &
auto	operator[] (const std::size_t index) noexcept -> InstructionExtra &
auto	release () &&-> std::vector< InstructionExtra >
	Hand the accumulated entries over to the template that will own them.

sourcemeta::blaze::Tweaks

struct sourcemeta::blaze::Tweaks

Advanced knobs that you can tweak for higher control and optimisations

Public Attributes
bool	properties_always_unroll {false}
	Always unroll properties in a logical AND operation.
bool	properties_reorder {true}
	Attempt to re-order properties subschemas to evaluate cheaper ones first.
std::size_t	target_inline_threshold {50}
	Inline jump targets with fewer instructions than this threshold.
bool	format_assertion {false}
	When set, force format to be compiled as an assertion.
std::optional< std::unordered_set< sourcemeta::core::JSON::StringView > >	annotations {}
std::uint64_t	max_instructions {std::numeric_limits<std::uint64_t>::max()}
std::uint64_t	max_depth {std::numeric_limits<std::uint64_t>::max()}

Member Data Documentation

annotations

std::optional<std::unordered_set<sourcemeta::core::JSON::StringView> > sourcemeta::blaze::Tweaks::annotations {}

Select which keywords emit annotations, regardless of the compilation mode. When not set, every annotation keyword is emitted in exhaustive mode and none in fast mode

max_depth

std::uint64_t sourcemeta::blaze::Tweaks::max_depth {std::numeric_limits<std::uint64_t>::max()}

How deep compilation may descend into a schema before it gives up and throws. Compiling a subschema recurses back into itself through the keyword handlers, so without this a schema nested deeply enough runs the stack out rather than reporting anything the caller can catch

max_instructions

std::uint64_t sourcemeta::blaze::Tweaks::max_instructions {std::numeric_limits<std::uint64_t>::max()}

How many instructions compilation may make before it gives up and throws. A schema compiles every target it can be entered through, and inlining copies what it inlines, so what an untrusted schema costs to compile grows faster than the schema itself does

sourcemeta::blaze::Context

struct sourcemeta::blaze::Context

The static compiler context is the information you have at your disposal to implement a keyword that will never change throughout the compilation process

Public Attributes
const sourcemeta::core::JSON &	root
	The root schema resource.
const sourcemeta::core::SchemaFrame &	frame
	The reference frame of the entire schema.
const std::vector< std::string >	resources
	The set of all schema resources in the schema without duplicates.
const sourcemeta::core::SchemaWalker &	walker
	The schema walker in use.
const sourcemeta::core::SchemaResolver &	resolver
	The schema resolver in use.
const Compiler &	compiler
	The schema compiler in use.
const Mode	mode
	The mode of the schema compiler.
const bool	uses_dynamic_scopes
	Whether the schema makes use of dynamic scoping.
const bool	collects_annotations
	Whether evaluating the schema may collect at least one annotation.
const SchemaUnevaluatedEntries	unevaluated
	The list of unevaluated entries and their dependencies.
const Tweaks	tweaks
	The set of tweaks for the compiler.
const std::map< std::tuple< sourcemeta::core::SchemaReferenceType, std::string_view, bool >, std::pair< std::size_t, const sourcemeta::core::WeakPointer * > >	targets
	All possible reference targets (key includes is_property_name context).
std::uint64_t &	depth
	How deep into the schema compilation currently is.
InstructionExtras &	extra
	Accumulator for instruction extra data during compilation.
std::vector< sourcemeta::core::SchemaVocabularies::URI > &	vocabularies
	Accumulator for the vocabularies that instructions refer to.

sourcemeta::blaze::KeywordContext

struct sourcemeta::blaze::KeywordContext

Everything a keyword is compiled against: the compilation as a whole, the subschema that declares the keyword, and the keyword itself

Public Member Functions
auto	keyword () const -> const sourcemeta::core::JSON::String &
	The keyword itself.
auto	value () const -> const sourcemeta::core::JSON &
	What the keyword is set to.
auto	schema () const -> const sourcemeta::core::JSON &
	The subschema that declares the keyword.
auto	vocabularies () const -> const sourcemeta::core::SchemaVocabularies &
	The vocabularies in force where the keyword is declared.
auto	base () const -> const sourcemeta::core::URI &
	The base URI of the subschema that declares the keyword.
auto	mode () const -> Mode
	The mode the whole schema is being compiled in.
auto	relative () const -> KeywordContext
Public Attributes
const Context &	global
	What holds for the entire compilation.
const SchemaContext &	local
	The subschema that the keyword belongs to.
DynamicContext	target

Member Function Documentation

relative()

auto sourcemeta::blaze::KeywordContext::relative ( ) const->KeywordContext

inlinenodiscard

The same subschema, addressed from where the keyword sits rather than from the base, which is what an applicator compiles its children against

Member Data Documentation

target

DynamicContext sourcemeta::blaze::KeywordContext::target

The keyword being compiled. Held by value, as the references it carries point at storage that outlives any context derived from it

sourcemeta::blaze::CompilerError

class sourcemeta::blaze::CompilerError

An error that represents a schema compilation failure event

Inheritance diagram for sourcemeta::blaze::CompilerError:

Public Member Functions
	CompilerError (sourcemeta::core::URI base, sourcemeta::core::Pointer schema_location, const char *message)
	CompilerError (sourcemeta::core::URI base, sourcemeta::core::Pointer schema_location, std::string message)=delete
	CompilerError (sourcemeta::core::URI base, sourcemeta::core::Pointer schema_location, std::string &&message)=delete
	CompilerError (sourcemeta::core::URI base, sourcemeta::core::Pointer schema_location, std::string_view message)=delete
auto	what () const noexcept -> const char *override
auto	base () const noexcept -> const sourcemeta::core::URI &
auto	location () const noexcept -> const sourcemeta::core::Pointer &

Member Function Documentation

location()

auto sourcemeta::blaze::CompilerError::location ( ) const->constsourcemeta::core::Pointer &

inlinenodiscardnoexcept

Where the problem is, as a pointer from the root of the document that the schema came from

sourcemeta::blaze::CompilerInvalidRegexError

class sourcemeta::blaze::CompilerInvalidRegexError

An error that represents an invalid regular expression during compilation

Inheritance diagram for sourcemeta::blaze::CompilerInvalidRegexError:

Public Member Functions
	CompilerInvalidRegexError (sourcemeta::core::URI base, sourcemeta::core::Pointer schema_location, std::string regex)
auto	what () const noexcept -> const char *override
auto	base () const noexcept -> const sourcemeta::core::URI &
auto	location () const noexcept -> const sourcemeta::core::Pointer &
auto	regex () const noexcept -> const std::string &

Member Function Documentation

location()

auto sourcemeta::blaze::CompilerInvalidRegexError::location ( ) const->constsourcemeta::core::Pointer &

inlinenodiscardnoexcept

Where the problem is, as a pointer from the root of the document that the schema came from

sourcemeta::blaze::CompilerReferenceTargetNotSchemaError

class sourcemeta::blaze::CompilerReferenceTargetNotSchemaError

An error that represents a reference target that is not a valid schema

Inheritance diagram for sourcemeta::blaze::CompilerReferenceTargetNotSchemaError:

Public Member Functions
	CompilerReferenceTargetNotSchemaError (const std::string_view identifier, sourcemeta::core::Pointer schema_location)
auto	what () const noexcept -> const char *override
auto	identifier () const noexcept -> const std::string &
auto	location () const noexcept -> const sourcemeta::core::Pointer &

Member Function Documentation

location()

auto sourcemeta::blaze::CompilerReferenceTargetNotSchemaError::location ( ) const->constsourcemeta::core::Pointer &

inlinenodiscardnoexcept

Where the problem is, as a pointer from the root of the document that the schema came from

sourcemeta::blaze::CompilerInstructionLimitError

class sourcemeta::blaze::CompilerInstructionLimitError

An error that represents a schema that compiles into more instructions than the caller was willing to spend on it

Inheritance diagram for sourcemeta::blaze::CompilerInstructionLimitError:

Public Member Functions
	CompilerInstructionLimitError (const std::uint64_t limit)
auto	what () const noexcept -> const char *override
auto	limit () const noexcept -> std::uint64_t
	The maximum number of instructions that compilation was allowed to make.

sourcemeta::blaze::CompilerDepthLimitError

class sourcemeta::blaze::CompilerDepthLimitError

An error that represents a schema that nests deeper than the caller was willing to descend into

Inheritance diagram for sourcemeta::blaze::CompilerDepthLimitError:

Public Member Functions
	CompilerDepthLimitError (const std::uint64_t limit)
auto	what () const noexcept -> const char *override
auto	limit () const noexcept -> std::uint64_t
	The deepest that compilation was allowed to descend.

sourcemeta::blaze::CompilerInvalidEntryPoint

class sourcemeta::blaze::CompilerInvalidEntryPoint

An error that represents an invalid compilation entrypoint

Inheritance diagram for sourcemeta::blaze::CompilerInvalidEntryPoint:

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

Typedef Documentation

Compiler

using sourcemeta::blaze::Compiler

Initial value:

 
    
    std::function<Instructions(const KeywordContext &, const Instructions &)>

A compiler is represented as a function that maps a keyword compiler context into a compiler template. You can provide your own to implement your own keywords

SchemaUnevaluatedEntries

using sourcemeta::blaze::SchemaUnevaluatedEntries

Initial value:

 
    std::map<sourcemeta::core::JSON::String, SchemaUnevaluatedEntry>

The flattened set of unevaluated cases in the schema by absolute URI

Function Documentation

compile() [1/3]

auto sourcemeta::blaze::compile	(	const KeywordContext &	context,
		const sourcemeta::core::WeakPointer &	schema_suffix,
		const sourcemeta::core::WeakPointer &	instance_suffix = sourcemeta::core::EMPTY_WEAK_POINTER,
		std::optional< std::string_view >	uri = std::nullopt )->Instructions

This function compiles a single subschema into a compiler template as determined by the given pointer. If a URI is given, the compiler will attempt to jump to that corresponding frame entry. Otherwise, it will navigate within the current keyword. This function is not meant to be used directly, but instead as a building block for supporting applicators on compiler functions.

compile() [2/3]

auto sourcemeta::blaze::compile	(	const sourcemeta::core::JSON &	schema,
		const sourcemeta::core::SchemaWalker &	walker,
		const sourcemeta::core::SchemaResolver &	resolver,
		const Compiler &	compiler,
		const Mode	mode = Mode::FastValidation,
		const std::string_view	default_dialect = "",
		const std::string_view	default_id = "",
		const std::string_view	entrypoint = "",
		const std::optional< Tweaks > &	tweaks = std::nullopt,
		std::uint64_t	max_locations = std::numeric_limits< std::uint64_t >::max() )->Template

This function compiles an input JSON Schema into a template that can be later evaluated. For example:

#include <sourcemeta/blaze/compiler.h>
 
#include <sourcemeta/core/json.h>
#include <sourcemeta/core/jsonschema.h>
 
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)};
 
// Evaluate or encode

This overload bundles and frames the schema before compiling it, and neither of those is bounded by the compiler tweaks. Pass max_locations to bound them instead. Bundling and framing each get this budget rather than sharing one, so the preamble costs at most twice it. The overload that takes a frame does neither, and so takes no such limit

compile() [3/3]

auto sourcemeta::blaze::compile	(	const sourcemeta::core::JSON &	schema,
		const sourcemeta::core::SchemaWalker &	walker,
		const sourcemeta::core::SchemaResolver &	resolver,
		const Compiler &	compiler,
		const sourcemeta::core::SchemaFrame &	frame,
		const std::string_view	entrypoint,
		const Mode	mode = Mode::FastValidation,
		const std::optional< Tweaks > &	tweaks = std::nullopt )->Template

This function compiles an input JSON Schema into a template that can be later evaluated, but given an existing schema frame. The schema frame must contain reference information for the given schema and the input schema must be bundled. If those pre-conditions are not met, you will hit undefined behavior.

Don't use this function unless you know what you are doing.

default_schema_compiler()

auto sourcemeta::blaze::default_schema_compiler	(	const KeywordContext &	,
		const Instructions &	)->Instructions

A default compiler that aims to implement every keyword for official JSON Schema dialects.

to_json()

auto sourcemeta::blaze::to_json

(

const Template &

schema_template

)

->sourcemeta::core::JSON

Serialise a template as JSON

Variable Documentation

EMPTY_KEYWORD

const sourcemeta::core::JSON::String sourcemeta::blaze::EMPTY_KEYWORD

A global constant instance of the empty schema keyword, which is what a context that names no keyword carries