name	last commit	date
.gitignore	Ignore generated test file	Mon Feb 28 23:42:18+0100 2022
LICENSE	Add LICENSE	Mon Mar 30 16:46:24+0200 2020
Makefile.am	Rely on guile-rdf for iri procedures.	Tue Mar 30 02:04:21+0200 2021
README.md	Add fromRdf algorithm	Sun Apr 12 20:55:37+0200 2020
bootstrap	Initial commit	Mon Mar 30 02:59:47+0200 2020
config.scm.in	Use a scheme file to propagate version from configure.ac	Sun Apr 12 23:49:39+0200 2020
configure.ac	Publish 1.0.1	Thu May 28 17:12:31+0200 2020
guile.am	Initial commit	Mon Mar 30 02:59:47+0200 2020
guix.scm	Update to guile-json-4	Tue Oct 06 04:27:51+0200 2020
jsonld/	Update compaction algorithm.	Mon Feb 28 23:41:27+0100 2022
jsonld.scm	Update compaction algorithm.	Mon Feb 28 23:41:27+0100 2022
pre-inst-env.in	Publish 1.0.1	Thu May 28 17:12:31+0200 2020
test-modules/	Rely on guile-rdf for iri procedures.	Tue Mar 30 02:04:21+0200 2021
tests/	Update compaction algorithm.	Mon Feb 28 23:41:27+0100 2022

Guile-JsonLD

Guile JsonLD is an implementation of the JsonLD API defined by the W3C for GNU Guile. JsonLD stands for Json for Linked Data. Linked Data is a representation for the semantic web. It allows you to express links between data, in a way that is very similar to WikiData for instance. An object can have relations (in the form of an IRI) that relates it to one or more objects, in the form of a Json object or an IRI at which another JsonLD document can usually be found, that represents that object.

JsonLD also defines different forms for a document, the expanded form being a somewhat canonical view of the document, where everything is explicit. The compact form is the form that is preferred for transfering a document: instead of explicit IRIs, it uses a less verbose format. A context is used to keep track of things and to allow a data consummer to get an expanded document back.

This implementation tries to follow the editor's draft of JsonLD 1.1 (and the final recommendation once published).

Installing

In order to install, your best option is to use the Guix package manager. It can run on any existing Linux distribution, and is guaranteed to not interact with its host distribution. Installing Guix is as simple as running the installation script. Once installed, you can run:

guix install guile guile-jsonld

Otherwise, your package manager might have guile-jsonld available. You can also build it from source, like so:

git clone https://framagit.org/tyreunom/guile-jsonld
autoreconf -fiv
./configure
make
sudo make install

You will need guile, guile-json and guile-rdf for it to work. Again, the best way to obtain the dependencies is to use Guix from this repository:

guix environment -l guix.scm

guix.scm is a file that is provided with this repository. You can use it to setup a development environment, as shown above, or to build the package, using maybe a different source, like this:

guix build --with-sources=guile-jsonld=$(PWD) -f guix.scm

Testing

The tests include running the official test suite. It requires network access. To run it, use:

make check

Please report any failure!

A test report can be generated in turtle format by running:

make report

This executes the same tests as make check above, but will save test results in the reports directory. This is used by developpers to send test results to the W3C's conformance report.

Documentation

This section documents the API, as implemented in this library. The API follows the “The Application Programming Interface” section of the documentation.

The JsonLDProcessor Interface

Our implementation of the JsonLDProcessor interface consists of the following functions:

Sheme Procedure: compact input context [#:options (new-jsonld-options)]

Compacts the given input using the context according to the steps in the Compaction algorithm. This procedure takes an input, which can be a Json object (as produced by the guile-json library) or a string representing the URL of a JsonLD document. The context is the content of the @context entry of the resulting document (in the format used by the guile-json library): this can be a simple string, an array of strings, or a JsonLD document with an @context key. The options can be used to carry additional configuration.

Scheme Procedure: expand input [#:options (new-jsonld-options)]

Expands the given input according to the steps in the Expansion algorithm. This procedure takes an input, which can be a Json object (as produced by the guile-jsonld library) or a string representing the URL of a JsonLD document. The options can be used to carry information about the base URI used during expansion, an additional context, and different options that control the behavior of the algorithm. See “The JsonLDOptions Type” section below.

Scheme Procedure: flatten input [#:context #f] [#:options (new-jsonld-options)]

Flattens the given input and optionally compacts it using the provided context according to the steps in the Flattening algorithm. This procedure takes and input, which can be a Json object (as produced by the guile-jsonld library) or a string representing the URL of a JsonLD document. The options can be used to carry additional configuration information. An additional context can be passed in order to run the compaction algorithm on the result.

Scheme Procedure: jsonld->rdf input [#:options (new-jsonld-options)]

Transforms the given input into an RDF dataset (in the format expected by guile-rdf). This procedure takes an input, which can be a Json object (as produced by the guile-json library) or a string representing the URL of a JsonLD document. The options can be used to carry additional configuration information.

Scheme Procedure: rdf->jsonld dataset [#:options (new-jsonld-options)]

Transforms the given dataset into a JsonLD document in expanded form. This procedure takes as input an RDF dataset (as produced by the guile-rdf library) and returns the same dataset in JsonLD format, in the expanded form. The options can be used to carry additional configuration information.

The JsonLDOptions Type

The jsonld-options type is used to pass various options to the JsonLdProcessor methods. This datatype is defined in the (jsonld options) module.

Scheme Datatype: jsonld-options

This type has the following fields:

base (default: #f): The base IRI to use when expanding or compacting the document. If set, this overrides the input document's IRI.
compact-arrays (default: #t): If set to true, the JSON-LD processor replaces arrays with just one element with that element during compaction. If set to false, all arrays will remain arrays even if they have just one element.
compact-to-relative (default: #t): Determines if IRIs are compacted relative to the base option or document location when compacting.
document-loader (default: (memoize download-json)): The callback of the loader to be used to retrieve remote documents and contexts, implementing the LoadDocumentCallback. It is used to retrieve remote documents and contexts.
expand-context (default: #f): A context that is used to initialize the active context when expanding a document.
extract-all-scripts (default: #f): If set to #t, when extracting JSON-LD script elements from HTML, unless a specific fragment identifier is targeted, extracts all encountered JSON-LD script elements using an array form, if necessary.
frame-expansion (default: #f): Enables special frame processing rules for the Expansion Algorithm. It also enables special rules for the Serialize RDF as JSON-LD Algorithm to use JSON-LD native types as values, where possible.
ordered (default: #f): If set to true, certain algorithm processing steps where indicated are ordered lexicographically. If false, order is not considered in processing.
processing-mode (default: "json-ld-1.1"): Sets the processing mode. If set to "json-ld-1.0" or "json-ld-1.1", the implementation must produce exactly the same results as the algorithms defined in this specification. If set to another value, the JSON-LD processor is allowed to extend or modify the algorithms defined in this specification to enable application-specific optimizations. We do not implement any application-specific optimization.
produce-generalized-rdf (default: #t): If set to true, the JSON-LD processor may emit blank nodes for triple predicates, otherwise they will be omitted.
rdf-direction (default: #f): Determines how value objects containing a base direction are transformed to and from RDF.
- If set to 'i18n-datatype, an RDF literal is generated using a datatype IRI based on https://www.w3.org/ns/i18n# with both the language tag (if present) and base direction encoded. When transforming from RDF, this datatype is decoded to create a value object containing @language (if present) and @direction.
- If set to 'compound-literal, a blank node is emitted instead of a literal, where the blank node is the subject of rdf:value, rdf:direction, and rdf:language (if present) properties. When transforming from RDF, this object is decoded to create a value object containing "@language" (if present) and "@direction".
use-native-types (default: #f): Causes the Serialize RDF as JSON-LD Algorithm to use native JSON values in value objects avoiding the need for an explicitly @type. useRdfType Enables special rules for the Serialize RDF as JSON-LD Algorithm causing rdf:type properties to be kept as IRIs in the output, rather than use @type.
use-rdf-type (default: #f): Enables special rules for the Serialize RDF as JSON-LD Algorithm causing rdf:type properties to be kept as IRIs in the output, rather than use @type.

Additionally, the module defines the following procedures:

Scheme Procedure: new-jsonld-options [#:base] [#:compact-arrays?] ...

Returns a new jsonld-options object with the fields filled with the corresponding keyword passed to this procedure, or with the default value if a keyword is not passed.

Scheme Procedure: update-jsonld-options options [#:base (jsonld-options-base options)] [#:compact-arrays? (jsonld-options-compact-arrays? options)] ...

Returns a new jsonld-options object with the fields filled with the corresponding keyword passed to this procedure, or with the value found in the required parameter options, another jsonld-options object, if the keyword is not passed.

Remote Document and Context Retrieval

This library implements a default document loader for JsonLD documents. It follows the section with the same name as this one in the JsonLD API specification. The (jsonld download) module defines the following procedure:

Scheme Procedure: download-json uri [#:mime-type "application/ld+json"] [#:extract-all-scripts? #f] [#:profile #f] [#:request-profile #f] [#:http-get http-get]

The download-json defines a callback that custom document loaders have to implement to be used to retrieve remote documents and contexts. The callback returns a json-document. On failure, the procedure throws an exception having an appropriate error code.

The uri is the location of the document and is a required parameter. All other parameters are optional. A custom callback does not have to implement the http-get parameter, nor the mime-type parameter, as they are not defined in the specification.

If set to true, when extracting JSON-LD script elements from HTML, unless a specific fragment identifier is targeted, extract-all-scripts? instructs the callback to extract all encountered JSON-LD script elements using an array form, if necessary.

When the resulting contentType is text/html or application/xhtml+xml, the profile option determines the profile to use for selecting JSON-LD script elements.

When set, the request-profile parameter contains one or more IRIs to use in the request as a profile parameter for the requested content type.

Scheme Datatype: json-document

This datatype represents a json document retrieved by the callback. This is the type of values returned by download-json. It has the following fields:

context-url (default: #f): If available, the value of the HTTP Link Header using the http://www.w3.org/ns/json-ld#context link relation in the response. If the response's Content-Type is application/ld+json, the HTTP Link Header is ignored. If multiple HTTP Link Headers using the http://www.w3.org/ns/json-ld#context link relation are found, download-json throws a multiple-context-link-headers exception.
document-url (default: #f): The final URL of the loaded document. This is important to handle HTTP redirects properly.
document (default: #f): The retrieved document, in the form returned by the guile-json library.
content-type (default: #f): The Content-Type of the loaded document, exclusive of any optional parameters.
profile (default: #f): The value of any profile parameter retrieved as part of the original contentType.

Additionally, this module provides the following procedure:

Scheme Procedure: new-json-document [#:context-url] [#:document-url] [#:document] [#:content-type] [#:profile]

Return a new json-document with the corresponding fields filled with the values that were passed, or #f if no matching keyword is passed to the procedure.

Error Handling

There are many JsonLD error types. When an error is encountered, the corresponding error code is thrown as a symbol representing this code. The following procedure can be used to get an English version of these errors, defined in the (jsonld json) module:

Scheme Procedure jsonld-error->string err

Converts an error symbol to a readable English string.