A collection of Blaze output processing utilities. More...

Classes
struct	sourcemeta::blaze::JSONLDResolutionError
class	sourcemeta::blaze::SimpleOutput
class	sourcemeta::blaze::TraceOutput

Typedefs
using	sourcemeta::blaze::JSONLDInvalid = std::vector<SimpleOutput::Entry>
using	sourcemeta::blaze::JSONLDOutcome

Enumerations
enum class	sourcemeta::blaze::JSONLDFacet : std::uint8_t { Type , Predicate , Datatype , Language , Direction , Graph , JSON , Container , Self , Override , ValuePredicate , Constants }
enum class	sourcemeta::blaze::StandardOutput : std::uint8_t { Flag , Basic }

Functions
auto	sourcemeta::blaze::jsonld (Evaluator &evaluator, const Template &schema, const sourcemeta::core::JSON &instance) -> JSONLDOutcome
auto	sourcemeta::blaze::standard (Evaluator &evaluator, const Template &schema, const sourcemeta::core::JSON &instance, const StandardOutput format) -> sourcemeta::core::JSON
auto	sourcemeta::blaze::standard (Evaluator &evaluator, const Template &schema, const sourcemeta::core::JSON &instance, const StandardOutput format, const sourcemeta::core::PointerPositionTracker &instance_tracker, const sourcemeta::core::Pointer &instance_base={}) -> sourcemeta::core::JSON

Variables
constexpr std::array< sourcemeta::core::JSON::StringView, 13 >	sourcemeta::blaze::JSONLD_KEYWORDS

Detailed Description

A collection of Blaze output processing utilities.

This functionality is included as follows:

#include <sourcemeta/blaze/output.h>

Class Documentation

◆ sourcemeta::blaze::JSONLDResolutionError

struct sourcemeta::blaze::JSONLDResolutionError

The instance conforms but one of its JSON-LD annotations cannot be resolved into a consistent mapping. Reported as a single failure at the instance location where resolution stopped, distinct from a schema validation error.

Public Attributes
sourcemeta::core::Pointer	instance_location
JSONLDFacet	facet
std::string	message
std::string	schema_location
	The schema location of the annotation the error is about.
std::optional< std::string >	conflicting_schema_location
std::optional< std::string >	inert_override_location

Member Data Documentation

◆ conflicting_schema_location

std::optional<std::string> sourcemeta::blaze::JSONLDResolutionError::conflicting_schema_location

The schema location of the annotation that the first one collides with, on errors involving a diverging or incompatible pair

◆ inert_override_location

std::optional<std::string> sourcemeta::blaze::JSONLDResolutionError::inert_override_location

The schema location of an x-jsonld-override mark that could not shadow the conflicting annotation it does not enclose

◆ sourcemeta::blaze::SimpleOutput

class sourcemeta::blaze::SimpleOutput

A simple evaluation callback that reports a stack trace in the case of validation error that you can report as you with. For example:

#include <sourcemeta/blaze/compiler.h>
#include <sourcemeta/blaze/evaluator.h>
#include <sourcemeta/blaze/output.h>
 
#include <sourcemeta/core/json.h>
#include <sourcemeta/core/jsonschema.h>
 
#include <cassert>
#include <functional>
 
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)};
 
const sourcemeta::core::JSON instance{5};
 
sourcemeta::blaze::SimpleOutput output{schema_template, instance};
sourcemeta::blaze::Evaluator evaluator;
const auto result{evaluator.validate(
  schema_template, instance, std::ref(output))};
 
if (!result) {
  for (const auto &entry : output) {
    std::cerr << entry.message << "\n";
    sourcemeta::core::stringify(entry.instance_location, std::cerr);
    std::cerr << "\n";
    sourcemeta::core::stringify(entry.evaluate_path, std::cerr);
    std::cerr << "\n";
  }
}

Public Types
using	container_type = std::vector<Entry>
using	const_iterator = container_type::const_iterator
Public Member Functions
	SimpleOutput (const Template &schema_template, const sourcemeta::core::JSON &instance, sourcemeta::core::WeakPointer base=sourcemeta::core::EMPTY_WEAK_POINTER)
	SimpleOutput (const SimpleOutput &)=delete
auto	operator= (const SimpleOutput &) -> SimpleOutput &=delete
auto	operator() (const EvaluationType type, const bool result, const Instruction &step, const InstructionExtra &step_metadata, const sourcemeta::core::WeakPointer &evaluate_path, const sourcemeta::core::WeakPointer &instance_location, const sourcemeta::core::JSON &annotation) -> void
auto	begin () const -> const_iterator
auto	end () const -> const_iterator
auto	cbegin () const -> const_iterator
auto	cend () const -> const_iterator
auto	release () &&-> container_type
auto	annotations () const -> const auto &

Member Function Documentation

◆ annotations()

auto sourcemeta::blaze::SimpleOutput::annotations ( ) const->constauto &

inlinenodiscard

Access the annotations collected during evaluation, as a flat log in evaluation order. The log records every emission as-is, so a location may repeat and hold the same value more than once. Consumers that need them grouped by location, or collapsed to distinct values, index this log themselves

◆ release()

auto sourcemeta::blaze::SimpleOutput::release ( ) &&->container_type

inlinenodiscard

Move out the collected error entries, leaving this output empty. Useful to take ownership of the trace without copying when the output is no longer needed

◆ sourcemeta::blaze::TraceOutput

class sourcemeta::blaze::TraceOutput

An evaluation callback that reports a trace of execution. For example:

#include <sourcemeta/blaze/compiler.h>
#include <sourcemeta/blaze/evaluator.h>
#include <sourcemeta/blaze/output.h>
 
#include <sourcemeta/core/json.h>
#include <sourcemeta/core/jsonschema.h>
 
#include <cassert>
#include <functional>
#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)};
 
const sourcemeta::core::JSON instance{5};
 
sourcemeta::blaze::TraceOutput output{schema_template,
    [](const sourcemeta::blaze::TraceOutput::Entry &entry) {
      std::cerr << entry.name << "\n";
    }};
sourcemeta::blaze::Evaluator evaluator;
const auto result{evaluator.validate(
  schema_template, instance, std::ref(output))};

Public Types
enum class	EntryType : std::uint8_t { Push , Pass , Fail , Annotation }
	The kind of entry being reported. Annotations are always valid.
using	Callback = std::function<void(const Entry &)>
Public Member Functions
	TraceOutput (const Template &schema_template, Callback callback, sourcemeta::core::WeakPointer base=sourcemeta::core::EMPTY_WEAK_POINTER)
	TraceOutput (const TraceOutput &)=delete
auto	operator= (const TraceOutput &) -> TraceOutput &=delete
auto	operator() (const EvaluationType type, const bool result, const Instruction &step, const InstructionExtra &step_metadata, const sourcemeta::core::WeakPointer &evaluate_path, const sourcemeta::core::WeakPointer &instance_location, const sourcemeta::core::JSON &annotation) -> void

Typedef Documentation

◆ JSONLDInvalid

using sourcemeta::blaze::JSONLDInvalid = std::vector<SimpleOutput::Entry>

The instance does not conform to the schema, so no JSON-LD is produced. These are the schema validation errors.

◆ JSONLDOutcome

using sourcemeta::blaze::JSONLDOutcome

Initial value:

std::variant<sourcemeta::core::JSON, JSONLDInvalid, JSONLDResolutionError>

The tri-state outcome of a JSON-LD evaluation: the expanded document (as expanded JSON-LD), schema validation errors, or a JSON-LD resolution error.

Enumeration Type Documentation

◆ JSONLDFacet

enum class sourcemeta::blaze::JSONLDFacet : std::uint8_t

strong

The descriptor facet that a JSON-LD resolution error is about

◆ StandardOutput

enum class sourcemeta::blaze::StandardOutput : std::uint8_t

strong

Represents standard output formats See https://json-schema.org/draft/2020-12/json-schema-core#name-output-structure See https://json-schema.org/draft/2019-09/draft-handrews-json-schema-02#rfc.section.10

Function Documentation

◆ jsonld()

auto sourcemeta::blaze::jsonld	(	Evaluator &	evaluator,
		const Template &	schema,
		const sourcemeta::core::JSON &	instance )->JSONLDOutcome

Evaluate an instance against a JSON Schema whose atoms carry JSON-LD annotations and, on success, return the instance promoted to expanded JSON-LD. The schema must have been compiled with annotation collection enabled for its JSON-LD keywords, as shown below. For example:

#include <sourcemeta/blaze/compiler.h>
#include <sourcemeta/blaze/evaluator.h>
#include <sourcemeta/blaze/output.h>
 
#include <sourcemeta/core/json.h>
#include <sourcemeta/core/jsonschema.h>
 
#include <unordered_set>
#include <variant>
 
const sourcemeta::core::JSON schema =
    sourcemeta::core::parse_json(R"JSON({
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "x-jsonld-type": "https://schema.org/Person",
  "properties": {
    "name": { "type": "string", "x-jsonld-id": "https://schema.org/name" }
  }
})JSON");
 
sourcemeta::blaze::Tweaks tweaks;
tweaks.annotations = std::unordered_set<sourcemeta::core::JSON::StringView>(
    sourcemeta::blaze::JSONLD_KEYWORDS.begin(),
    sourcemeta::blaze::JSONLD_KEYWORDS.end());
 
const auto schema_template{sourcemeta::blaze::compile(
    schema, sourcemeta::core::schema_walker,
    sourcemeta::core::schema_resolver,
    sourcemeta::blaze::default_schema_compiler,
    sourcemeta::blaze::Mode::FastValidation, "", "", "", tweaks)};
 
const sourcemeta::core::JSON instance{
    sourcemeta::core::parse_json(R"JSON({ "name": "Ada" })JSON")};
 
sourcemeta::blaze::Evaluator evaluator;
const auto outcome{
    sourcemeta::blaze::jsonld(evaluator, schema_template, instance)};

◆ standard() [1/2]

auto sourcemeta::blaze::standard	(	Evaluator &	evaluator,
		const Template &	schema,
		const sourcemeta::core::JSON &	instance,
		const StandardOutput	format )->sourcemeta::core::JSON

Perform JSON Schema evaluation using Standard Output formats. For example:

#include <sourcemeta/blaze/compiler.h>
#include <sourcemeta/blaze/evaluator.h>
#include <sourcemeta/blaze/output.h>
 
#include <sourcemeta/core/json.h>
#include <sourcemeta/core/jsonschema.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::core::schema_walker,
    sourcemeta::core::schema_resolver,
    sourcemeta::blaze::default_schema_compiler)};
 
const sourcemeta::core::JSON instance{"foo bar"};
 
sourcemeta::blaze::Evaluator evaluator;
 
const auto result{sourcemeta::blaze::standard(
  evaluator, schema_template, instance,
  sourcemeta::blaze::StandardOutput::Basic)};
 
assert(result.is_object());
assert(result.defines("valid"));
assert(result.at("valid").is_boolean());
assert(result.at("valid").to_boolean());
 
sourcemeta::core::prettify(result, std::cout);
std::cout << "\n";

Note that this output format is not a class like the others in order to have additional control over how and whether to pass a callback to the evaluator instance.

◆ standard() [2/2]

auto sourcemeta::blaze::standard	(	Evaluator &	evaluator,
		const Template &	schema,
		const sourcemeta::core::JSON &	instance,
		const StandardOutput	format,
		const sourcemeta::core::PointerPositionTracker &	instance_tracker,
		const sourcemeta::core::Pointer &	instance_base = {} )->sourcemeta::core::JSON

An overload of the standard output function that includes line and column position information as an extension.

When validating a subtree of the document the given tracker was populated from, set instance_base to the location of that subtree within the document. The reported instance locations remain relative to the instance that was validated, as the specification mandates, while positions are looked up from the base, as they refer to the document as a whole.

Variable Documentation

◆ JSONLD_KEYWORDS

std::array<sourcemeta::core::JSON::StringView, 13> sourcemeta::blaze::JSONLD_KEYWORDS

inlineconstexpr