JSON-LD

A JSON-LD 1.1 processor, with support for the JSON-LD 1.0 processing mode. More...

Classes
class	sourcemeta::core::JSONLDError
class	sourcemeta::core::JSONLDFragmentError
struct	sourcemeta::core::JSONLDEdge
struct	sourcemeta::core::JSONLDNode
struct	sourcemeta::core::JSONLDLiteral
struct	sourcemeta::core::JSONLDReference
struct	sourcemeta::core::JSONLDPromotion
struct	sourcemeta::core::JSONLDCollection
struct	sourcemeta::core::JSONLDDescriptor
struct	sourcemeta::core::JSONLDBasicAnnotation< PointerT >

Typedefs
using	sourcemeta::core::JSONLDResolver = std::function<std::optional<JSON>(JSON::StringView)>
template<typename PointerT>
using	sourcemeta::core::JSONLDBasicAnnotationList = std::vector<JSONLDBasicAnnotation<PointerT>>
using	sourcemeta::core::JSONLDAnnotationList = JSONLDBasicAnnotationList<Pointer>
using	sourcemeta::core::JSONLDWeakAnnotationList = JSONLDBasicAnnotationList<WeakPointer>

Enumerations
enum class	sourcemeta::core::JSONLDVersion : std::uint8_t { JSONLDVersion::V1_0 , JSONLDVersion::V1_1 }
enum class	sourcemeta::core::JSONLDDirection : std::uint8_t { JSONLDDirection::LTR , JSONLDDirection::RTL }
enum class	sourcemeta::core::JSONLDContainer : std::uint8_t { JSONLDContainer::List , JSONLDContainer::Set , JSONLDContainer::Language , JSONLDContainer::Index }

Functions
SOURCEMETA_CORE_JSONLD_EXPORT auto	sourcemeta::core::jsonld_expand (const JSON &input, const JSON::StringView base_iri="", const JSONLDResolver &resolver={}, const JSONLDVersion version=JSONLDVersion::V1_1) -> JSON
SOURCEMETA_CORE_JSONLD_EXPORT auto	sourcemeta::core::jsonld_expand (const JSON &input, const JSON &expand_context, const JSON::StringView base_iri="", const JSONLDResolver &resolver={}, const JSONLDVersion version=JSONLDVersion::V1_1) -> JSON
SOURCEMETA_CORE_JSONLD_EXPORT auto	sourcemeta::core::jsonld_is_expanded (const JSON &document) -> bool
SOURCEMETA_CORE_JSONLD_EXPORT auto	sourcemeta::core::jsonld_compact (const JSON &input, const JSON &context, const JSON::StringView base_iri="", const JSONLDResolver &resolver={}, const JSONLDVersion version=JSONLDVersion::V1_1, const bool compact_arrays=true, const bool compact_to_relative=true) -> JSON
SOURCEMETA_CORE_JSONLD_EXPORT auto	sourcemeta::core::jsonld_flatten (const JSON &input) -> JSON
SOURCEMETA_CORE_JSONLD_EXPORT auto	sourcemeta::core::jsonld_flatten (const JSON &input, const JSON &context, const JSON::StringView base_iri="", const JSONLDResolver &resolver={}, const JSONLDVersion version=JSONLDVersion::V1_1, const bool compact_arrays=true) -> JSON
SOURCEMETA_CORE_JSONLD_EXPORT auto	sourcemeta::core::jsonld_materialize (const JSON &instance, const JSONLDAnnotationList &annotations) -> JSON
SOURCEMETA_CORE_JSONLD_EXPORT auto	sourcemeta::core::jsonld_materialize (const JSON &instance, const JSONLDWeakAnnotationList &annotations) -> JSON
SOURCEMETA_CORE_JSONLD_EXPORT auto	sourcemeta::core::jsonld_canonicalize_fragment (const JSON &fragment) -> JSON

Detailed Description

A JSON-LD 1.1 processor, with support for the JSON-LD 1.0 processing mode.

This functionality is included as follows:

#include <sourcemeta/core/jsonld.h>

---

Class Documentation

sourcemeta::core::JSONLDError

class sourcemeta::core::JSONLDError

An error that represents a JSON-LD processing failure. The message is one of the error codes defined by the JSON-LD 1.1 API specification, and the pointer locates the offending position in the input document

Inheritance diagram for sourcemeta::core::JSONLDError:

Public Member Functions
	JSONLDError (const char *code, Pointer pointer)
	Locate the error at an owned pointer.
	JSONLDError (const char *code, const WeakPointer &pointer)
	Locate the error at a weak pointer, materialising an owned pointer.
	JSONLDError (const char *code, const WeakPointer &pointer, const std::initializer_list< JSON::StringView > children)

Constructor & Destructor Documentation

JSONLDError()

sourcemeta::core::JSONLDError::JSONLDError ( const char * code, const WeakPointer & pointer, const std::initializer_list< JSON::StringView > children )

inline

Locate the error at a weak pointer extended with the given trailing property tokens.

sourcemeta::core::JSONLDFragmentError

class sourcemeta::core::JSONLDFragmentError

An error that represents a constants fragment grammar violation. The message states the violated fragment rule, the key names the offending fragment entry, and the pointer locates the offending value inside the fragment

Inheritance diagram for sourcemeta::core::JSONLDFragmentError:

Public Member Functions
	JSONLDFragmentError (const char *code, Pointer pointer, JSON::String key)
	Locate the error at a fragment entry.
auto	key () const noexcept -> const JSON::String &
Public Member Functions inherited from sourcemeta::core::JSONLDError
	JSONLDError (const char *code, Pointer pointer)
	Locate the error at an owned pointer.
	JSONLDError (const char *code, const WeakPointer &pointer)
	Locate the error at a weak pointer, materialising an owned pointer.
	JSONLDError (const char *code, const WeakPointer &pointer, const std::initializer_list< JSON::StringView > children)

Member Function Documentation

key()

auto sourcemeta::core::JSONLDFragmentError::key ( ) const -> const JSON::String &

inlinenodiscardnoexcept

Get the key of the fragment entry that caused the error, empty when the fragment itself is malformed

sourcemeta::core::JSONLDEdge

struct sourcemeta::core::JSONLDEdge

How a position connects to its parent. The position is the object of the edge, asserted in reverse when the flag is set.

Public Attributes
JSON::String	predicate {}
	The predicate that connects the position to its parent.
bool	reverse {false}
	Whether the edge is asserted in reverse.

sourcemeta::core::JSONLDNode

struct sourcemeta::core::JSONLDNode

A position that is an object. An absent identifier means a fresh blank node, and the graph flag asserts the node's descendants in the named graph the identifier denotes.

Public Attributes
std::optional< JSON::String >	id {}
	The node identifier, absent for a fresh blank node.
std::vector< JSON::String >	types {}
	The types of the node.
bool	graph {false}
	Whether the node's descendants are asserted in the named graph it denotes.
JSON	constants {JSON::make_object()}

Member Data Documentation

constants

JSON sourcemeta::core::JSONLDNode::constants {JSON::make_object()}

Constant properties merged into the node, as a canonical fragment of predicate to term array whose entries are all non-empty term arrays, never null removal entries. May be empty.

sourcemeta::core::JSONLDLiteral

struct sourcemeta::core::JSONLDLiteral

A position that is a value. The datatype defaults to the native type of the JSON value, a language may carry a direction, and the JSON flag preserves an opaque JSON literal verbatim.

Public Attributes
std::optional< JSON::String >	datatype {}
std::optional< JSON::String >	language {}
	The language tag of the literal.
std::optional< JSONLDDirection >	direction {}
	The base direction of the literal.
bool	json {false}
	Whether the literal is preserved as an opaque JSON literal.

Member Data Documentation

datatype

std::optional<JSON::String> sourcemeta::core::JSONLDLiteral::datatype {}

The literal datatype, defaulting to the native type of the value. An explicit datatype carries a native number or boolean as its canonical string lexical form.

sourcemeta::core::JSONLDReference

struct sourcemeta::core::JSONLDReference

A scalar promoted to an identified node

Public Attributes
JSON::String	id {}
	The identifier of the promoted node.
std::vector< JSON::String >	types {}
	The types of the promoted node.
JSON	constants {JSON::make_object()}

Member Data Documentation

constants

JSON sourcemeta::core::JSONLDReference::constants {JSON::make_object()}

Constant properties merged into the node, as a canonical fragment of predicate to term array whose entries are all non-empty term arrays, never null removal entries. May be empty.

sourcemeta::core::JSONLDPromotion

struct sourcemeta::core::JSONLDPromotion

A scalar promoted to a node that carries the scalar as a literal under a value predicate, plus constant properties. A null value at a promoted position materializes nothing, as constant properties never appear without the scalar that legitimizes them.

Public Attributes
std::optional< JSON::String >	id {}
	The node identifier, absent for a fresh blank node.
std::vector< JSON::String >	types {}
	The types of the promoted node.
JSON::String	value {}
	The predicate that carries the scalar.
JSONLDLiteral	literal {}
JSON	constants {JSON::make_object()}

Member Data Documentation

constants

JSON sourcemeta::core::JSONLDPromotion::constants {JSON::make_object()}

Constant properties merged into the node, as a canonical fragment of predicate to term array whose entries are all non-empty term arrays, never null removal entries. May be empty.

literal

JSONLDLiteral sourcemeta::core::JSONLDPromotion::literal {}

The literal facets of the carried scalar. The opaque JSON literal facet does not apply to a promoted scalar and must stay unset.

sourcemeta::core::JSONLDCollection

struct sourcemeta::core::JSONLDCollection

A position that is a collection. A List is asserted as an RDF list and a Set as a set, both ranging over an array. A Language container ranges over an object of language tag to string, and an Index container over an object whose keys are index labels that carry no RDF.

Public Attributes
JSONLDContainer	container {JSONLDContainer::Set}
	The container form of the collection.

sourcemeta::core::JSONLDDescriptor

struct sourcemeta::core::JSONLDDescriptor

The semantics of a single instance position: how it connects to its parent and what it is

Public Attributes
std::vector< JSONLDEdge >	edges {}
	How the position connects to its parent.
std::variant< JSONLDNode, JSONLDLiteral, JSONLDReference, JSONLDCollection, JSONLDPromotion >	value {}
	What the position is.

sourcemeta::core::JSONLDBasicAnnotation

struct sourcemeta::core::JSONLDBasicAnnotation

template<typename PointerT>
struct sourcemeta::core::JSONLDBasicAnnotation< PointerT >

An instance position paired with its JSON-LD semantics

Public Attributes
JSONLDDescriptor	descriptor {}
	The JSON-LD semantics of the position.

Typedef Documentation

JSONLDAnnotationList

using sourcemeta::core::JSONLDAnnotationList = JSONLDBasicAnnotationList<Pointer>

An annotation list whose positions are owning JSON Pointers

JSONLDBasicAnnotationList

template<typename PointerT>

using sourcemeta::core::JSONLDBasicAnnotationList = std::vector<JSONLDBasicAnnotation<PointerT>>

A flat collection of annotated instance positions, in any order. When more than one entry describes the same position, the first one wins.

JSONLDResolver

using sourcemeta::core::JSONLDResolver = std::function<std::optional<JSON>(JSON::StringView)>

A resolver callback for loading remote JSON-LD contexts referenced during expansion. Given an absolute IRI, it returns the referenced document, or no value if it cannot be resolved.

JSONLDWeakAnnotationList

using sourcemeta::core::JSONLDWeakAnnotationList = JSONLDBasicAnnotationList<WeakPointer>

An annotation list whose positions are non-owning weak JSON Pointers. The positions reference strings owned elsewhere that must outlive any materialization call.

Enumeration Type Documentation

JSONLDContainer

enum class sourcemeta::core::JSONLDContainer : std::uint8_t

strong

The container form of a collection position. List and Set range over an array; Language and Index range over an object.

Enumerator
List	An ordered RDF list ranging over an array.
Set	An unordered set ranging over an array.
Language	A map of language tag to string ranging over an object.
Index	A map of index labels carrying no RDF ranging over an object.

JSONLDDirection

enum class sourcemeta::core::JSONLDDirection : std::uint8_t

strong

The base direction of a language-tagged string

Enumerator
LTR	The left-to-right base direction.
RTL	The right-to-left base direction.

JSONLDVersion

enum class sourcemeta::core::JSONLDVersion : std::uint8_t

strong

The JSON-LD processing mode

Enumerator
V1_0	The JSON-LD 1.0 processing mode.
V1_1	The JSON-LD 1.1 processing mode.

Function Documentation

jsonld_canonicalize_fragment()

SOURCEMETA_CORE_JSONLD_EXPORT auto sourcemeta::core::jsonld_canonicalize_fragment

(

const JSON &

fragment

)

-> JSON

Validate a fragment of constant node properties written in a restricted expanded form and return its canonical form: keys sorted, bare scalars and single terms wrapped into term arrays, duplicate terms removed, and native numbers or booleans paired with an explicit datatype rewritten to their canonical string lexical form. A grammar violation throws. A null entry passes through untouched as the caller's removal channel, so a canonical fragment only becomes usable as descriptor constants once the caller resolves removals and strips the null entries. For example:

#include <sourcemeta/core/jsonld.h>
 
#include <cassert>
 
const auto fragment{sourcemeta::core::parse_json(R"({
  "https://example.com/unit": { "@id": "https://example.com/metre" }
})")};
 
const auto canonical{
    sourcemeta::core::jsonld_canonicalize_fragment(fragment)};
assert(canonical.at("https://example.com/unit").is_array());

jsonld_compact()

SOURCEMETA_CORE_JSONLD_EXPORT auto sourcemeta::core::jsonld_compact	(	const JSON &	input,
		const JSON &	context,
		const JSON::StringView	base_iri = "",
		const JSONLDResolver &	resolver = {},
		const JSONLDVersion	version = JSONLDVersion::V1_1,
		const bool	compact_arrays = true,
		const bool	compact_to_relative = true ) -> JSON

Compact a JSON-LD document in expanded form against the given context to produce a friendlier shape. The input must already be expanded, and the result carries the given context. For example:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/jsonld.h>
#include <iostream>
 
const auto document{sourcemeta::core::parse_json(R"([
  { "http://schema.org/name": [ { "@value": "Sourcemeta" } ] }
])")};
 
const auto context{sourcemeta::core::parse_json(R"({
  "name": "http://schema.org/name"
})")};
 
const auto compacted{sourcemeta::core::jsonld_compact(document, context)};
sourcemeta::core::prettify(compacted, std::cout);
std::cout << std::endl;

jsonld_expand() [1/2]

SOURCEMETA_CORE_JSONLD_EXPORT auto sourcemeta::core::jsonld_expand	(	const JSON &	input,
		const JSON &	expand_context,
		const JSON::StringView	base_iri = "",
		const JSONLDResolver &	resolver = {},
		const JSONLDVersion	version = JSONLDVersion::V1_1 ) -> JSON

Expand a JSON-LD document, applying the given expansion context before the document's own context, as if it had been prepended to the input. For example:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/jsonld.h>
#include <iostream>
 
const auto document{sourcemeta::core::parse_json(
    R"({ "name": "Sourcemeta" })")};
const auto context{sourcemeta::core::parse_json(
    R"({ "name": "https://schema.org/name" })")};
 
const auto expanded{sourcemeta::core::jsonld_expand(document, context)};
sourcemeta::core::prettify(expanded, std::cout);
std::cout << std::endl;

jsonld_expand() [2/2]

SOURCEMETA_CORE_JSONLD_EXPORT auto sourcemeta::core::jsonld_expand	(	const JSON &	input,
		const JSON::StringView	base_iri = "",
		const JSONLDResolver &	resolver = {},
		const JSONLDVersion	version = JSONLDVersion::V1_1 ) -> JSON

Expand a JSON-LD document into its expanded form, resolving relative references against the given base IRI and loading any remote context through the given resolver. The result is always a JSON array. For example:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/jsonld.h>
#include <iostream>
 
const auto document{sourcemeta::core::parse_json(R"({
  "@context": { "name": "https://schema.org/name" },
  "name": "Sourcemeta"
})")};
 
const auto expanded{sourcemeta::core::jsonld_expand(document)};
sourcemeta::core::prettify(expanded, std::cout);
std::cout << std::endl;

jsonld_flatten() [1/2]

SOURCEMETA_CORE_JSONLD_EXPORT auto sourcemeta::core::jsonld_flatten

(

const JSON &

input

)

-> JSON

Flatten a JSON-LD document in expanded form, collecting the properties of each node into a single node object and labelling blank nodes. The input must already be expanded. For example:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/jsonld.h>
#include <iostream>
 
const auto document{sourcemeta::core::parse_json(R"([
  {
    "@id": "http://example.com/a",
    "http://example.com/b": [ { "@id": "http://example.com/c" } ]
  }
])")};
 
const auto flattened{sourcemeta::core::jsonld_flatten(document)};
sourcemeta::core::prettify(flattened, std::cout);
std::cout << std::endl;

jsonld_flatten() [2/2]

SOURCEMETA_CORE_JSONLD_EXPORT auto sourcemeta::core::jsonld_flatten	(	const JSON &	input,
		const JSON &	context,
		const JSON::StringView	base_iri = "",
		const JSONLDResolver &	resolver = {},
		const JSONLDVersion	version = JSONLDVersion::V1_1,
		const bool	compact_arrays = true ) -> JSON

Flatten a JSON-LD document in expanded form and compact the result against the given context. The input must already be expanded, and the result carries the given context. For example:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/jsonld.h>
#include <iostream>
 
const auto document{sourcemeta::core::parse_json(R"([
  { "http://schema.org/name": [ { "@value": "Sourcemeta" } ] }
])")};
 
const auto context{sourcemeta::core::parse_json(R"({
  "name": "http://schema.org/name"
})")};
 
const auto flattened{sourcemeta::core::jsonld_flatten(document, context)};
sourcemeta::core::prettify(flattened, std::cout);
std::cout << std::endl;

jsonld_is_expanded()

SOURCEMETA_CORE_JSONLD_EXPORT auto sourcemeta::core::jsonld_is_expanded

(

const JSON &

document

)

-> bool

Determine whether a document is in the JSON-LD 1.1 expanded document form: an array of node objects that carries no context and whose keys are all absolute IRIs, blank node identifiers, or keywords. For example:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/jsonld.h>
#include <cassert>
 
const auto document{sourcemeta::core::parse_json(R"([
  { "http://schema.org/name": [ { "@value": "Sourcemeta" } ] }
])")};
 
assert(sourcemeta::core::jsonld_is_expanded(document));

jsonld_materialize() [1/2]

SOURCEMETA_CORE_JSONLD_EXPORT auto sourcemeta::core::jsonld_materialize	(	const JSON &	instance,
		const JSONLDAnnotationList &	annotations ) -> JSON

Materialize an instance into expanded JSON-LD using an annotation list that assigns JSON-LD semantics to instance positions. An undescribed member of a collection defaults to a plain literal, or to a collection of the enclosing kind for a nested array. The result is always a JSON array. For example:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/jsonld.h>
#include <iostream>
 
const auto instance{sourcemeta::core::parse_json(
    R"({ "name": "Sourcemeta" })")};
 
sourcemeta::core::JSONLDAnnotationList annotations;
annotations.push_back(
    {sourcemeta::core::Pointer{},
     sourcemeta::core::JSONLDDescriptor{
         {}, sourcemeta::core::JSONLDNode{
                 "https://example.com/org", {}, false }}});
annotations.push_back(
    {sourcemeta::core::Pointer{"name"},
     sourcemeta::core::JSONLDDescriptor{
         { { "https://schema.org/name", false } },
         sourcemeta::core::JSONLDLiteral{}}});
 
const auto expanded{
    sourcemeta::core::jsonld_materialize(instance, annotations)};
sourcemeta::core::prettify(expanded, std::cout);
std::cout << std::endl;

jsonld_materialize() [2/2]

SOURCEMETA_CORE_JSONLD_EXPORT auto sourcemeta::core::jsonld_materialize	(	const JSON &	instance,
		const JSONLDWeakAnnotationList &	annotations ) -> JSON

Materialize an instance into expanded JSON-LD using a weak annotation list whose positions are non-owning views into strings owned elsewhere. The backing strings must outlive the call. An undescribed member of a collection defaults to a plain literal, or to a collection of the enclosing kind for a nested array. The result is always a JSON array. For example:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/jsonld.h>
#include <functional>
#include <iostream>
 
const auto instance{sourcemeta::core::parse_json(
    R"({ "name": "Sourcemeta" })")};
 
const sourcemeta::core::JSON::String name_key{"name"};
 
sourcemeta::core::JSONLDWeakAnnotationList annotations;
annotations.push_back(
    {sourcemeta::core::WeakPointer{},
     sourcemeta::core::JSONLDDescriptor{
         {}, sourcemeta::core::JSONLDNode{
                 "https://example.com/org", {}, false }}});
annotations.push_back(
    {sourcemeta::core::WeakPointer{std::cref(name_key)},
     sourcemeta::core::JSONLDDescriptor{
         { { "https://schema.org/name", false } },
         sourcemeta::core::JSONLDLiteral{}}});
 
const auto expanded{
    sourcemeta::core::jsonld_materialize(instance, annotations)};
sourcemeta::core::prettify(expanded, std::cout);
std::cout << std::endl;