guile-jsonld/README.md

README.md

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:

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:

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.