RML Playground

A browser-based editor meant for writing RML rules, supported by the Semantic Web Language Server (SWLS) The rules can be executed on a sample of the data, which allows users to inspect the generated RDF data. The generated RDF data can be exported for use outside of the RML Playground.

Table of contents

• Requirements
• Installation
• Usage
  • Setting up the RMLMapper Web API endpoint
  • Configuring the RML Playground
• Additional configuration sets
• Developing
  • Installation
  • Debugging
  • Building
• Run tests
• License

Requirements

Node.js

Installation

npm install

Usage

Setting up the RMLMapper Web API endpoint

The RML Playground generates RDF data through a remote server. For this, the RML Playground requires you to provide an RML mapping engine endpoint. You can either provide the URL of an existing server, or set one up yourself by following these instructions. Make sure that you provide the correct URL for the endpoint during configuration.

Configuring the RML Playground

To configure RML Playground, create a configuration file config.json in the project root. The configuration options are (all keys are optional unless noted):

• "title": (string) Title displayed in the browser tab and as page header.
• "logo": (string) "logo_kgc" or "logo_rmlio".
• "surveyUrl": (string) URL used for the feedback / survey link in the UI.
• "RMLspecifications": (array of objects, optional) Array of RML specification objects, each with url and label properties.
• "RMLengine": (object) Object containing RML mapping engine information:
  • "url": (string) URL or documentation link for the RML engine.
  • "label": (string) Display name for the RML engine.
  • "webAPI": (string) URL of the RMLMapper Web API endpoint used to execute mappings.
• "SWLSconfig": (Object) Settings for the Semantic Web Language Server:
  • ontologies: (array of strings) URLs of ontology resources
  • shapes: (array of strings) URLs of SHACL shape files
  • prefix_disabled: (array of strings) Prefixes of ontologies that must not be imported from LOV
  • completion: (object): Autocompetion settings with two keys:
    • strict: (array of strings): URLs of namespace requiring strict autocompletion (respecting the defined domain)
    • loose: (array of strings): URLs of namespace requiring loose autocompletion
• "examples": (array of objects) Example objects used to populate the examples dropdown. Each example is a JSON object describing the mapping, input data and metadata.

Notes:

• The file config.json is git-ignored. If you do not provide one, the build scripts copy config-default.json into place.
• You can add more logo's in ./lib/resources, with update in ./lib/front.js.

Additional configuration sets

You can maintain multiple configuration sets under the configs/ folder. Each configuration should be placed in its own subdirectory and contain a config.json with an additional key èxampleDirs with the relative paths to example subfolders inside that subdirectory, containing:

• metadata.json — metadata file with id, label, mapping (filename), and data (array of file objects)
• a mapping file - referenced in metadata.json
• data files — referenced in metadata.json

configs/
  config1/
    config.json
    examples/
      example1/ 
        input1.json
        mapping.ttl
        metadata.json
  config2/
    config.json
    examples/
      example1/ 
        input1.json
        mapping.ttl
        metadata.json
      example2/ 
        input1.csv
        mapping.ttl
        metadata.json

To activate one of these configurations, run the helper script:

node scripts/select-config.cjs <config-name>
# example
node scripts/select-config.cjs rmlio

This script will add the examples from the subfolders to the selected config.json, before placing the config in the root of this repository.

Developing

Installation

Install dependencies via

npm install

Debugging

1. Build for debugging and spin up an HTTP server via

   npm run dev

2. Open http://localhost:5173 in the browser.

Building

Build a minimized version into ./dist:

npm run build

Run tests

NOTE: the tests are temporarily disabled.

Run the following commands from inside the project directory:

npm install
# for CI/CD, assuming that an RMLMapper endpoint with URL <https://rml.io/api/rmlmapper/execute> is up and running:
npm test
# for local testing, assuming that an RMLMapper endpoint with URL <http://localhost:4000/execute> is up and running:
npm run test-local

License

This code is copyrighted by Ghent University – imec and released under the MIT license.