Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/ULB-Darmstadt/shacl-form

HTML5 web component for editing/viewing RDF data that conform to SHACL shapes
https://github.com/ULB-Darmstadt/shacl-form

editor rdf shacl validation viewer

Last synced: 19 days ago
JSON representation

HTML5 web component for editing/viewing RDF data that conform to SHACL shapes

Awesome Lists containing this project

README 

        
# SHACL Form Generator



```console

npm i @ulb-darmstadt/shacl-form

```



HTML5 web component for editing/viewing [RDF](https://www.w3.org/RDF/) data that conform to [SHACL shapes](https://www.w3.org/TR/shacl/).



## [See demo here](https://ulb-darmstadt.github.io/shacl-form/)



### Basic usage



```html



  

    

    

  

  

    

    



    

      const form = document.querySelector("shacl-form")

      form.addEventListener('change', event => {

        // check if form data validates according to the SHACL shapes

        if (event.detail?.valid) {

          // get data graph as RDF triples and

          // log them to the browser console

          const triples = form.serialize() 

          console.log('entered form data', triples)

          // store the data somewhere, e.g. in a triple store

        }

      })

    

  



```



### Element attributes



Attribute | Description

---|---

data-shapes | SHACL shape definitions (e.g. a turtle string) to generate the form from

data-shapes-url | When `data-shapes` is not set, the SHACL shapes are loaded from this URL

data-shape-subject | Optional subject (id) of the SHACL node shape to use as root for the form. If not set, the first found node shape will be used

data-values | RDF triples (e.g. a turtle string) to use as existing data graph to fill the form

data-values-url | When `data-values` is not set, the data graph triples are loaded from this URL

data-values-subject | The subject (id) of the generated data. If this is not set, a blank node with a new UUID is created. If `data-values` or `data-values-url` is set, this id is also used to find the root node in the data graph to fill the form

data-values-namespace | RDF namespace to use when generating new RDF subjects. Default is empty, so that subjects will be blank nodes.

data-values-graph | If set, serializing the form will create a named graph with the given IRI.

data-language | Language to use if shapes contain langStrings, e.g. in `sh:name` or `rdfs:label`. Default is [`navigator.language`](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/language) with fallback to [`navigator.languages`](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/languages)

data-loading | Text to display while the web component is initializing. Default: `"Loading..."`

data‑ignore‑owl‑imports | By default, `owl:imports` URLs are fetched and the resulting RDF triples are added to the shapes graph. Setting this attribute to any value disables this feature

data-view | When set, turns the web component into a viewer that displays the given data graph without editing functionality

data-collapse | When set, `sh:group`s and properties with `sh:node` and `sh:maxCount` != 1 are displayed in a collapsible accordion-like widget to reduce visual complexity of the form. The collapsible element is initially shown closed, except when this attribute's value is `"open"`

data-submit-button | [Ignored when `data-view` attribute is set] Whether to add a submit button to the form. The value of this attribute is used as the button label. `submit` events get emitted only when the form data validates

data-generate-node-shape-reference | When generating the RDF data graph, <shacl-form> can create a triple that references the root `sh:NodeShape` of the data. Suggested values for this attribute are `http://www.w3.org/1999/02/22-rdf-syntax-ns#type` or `http://purl.org/dc/terms/conformsTo`. Default is empty, so that no such triple is created

data-show-node-ids | When this attribute is set, shacl node shapes will have their subject id shown in the form



### Element functions





```typescript

toRDF(graph?: Store): Store

```

Adds the form values as RDF triples to the given graph. If no graph object is provided, creates a new [N3 Store](https://github.com/rdfjs/N3.js#storing).



```typescript

serialize(format?: string, graph?: Store): string

```

Serializes the given RDF graph to the given format. If no graph object is provided, this function calls toRDF() (see above) to construct the form data graph. Supported formats:  `text/turtle` (default), `application/ld+json`, `application/n-triples`, `application/n-quads`, `application/trig`.



```typescript

validate(ignoreEmptyValues: boolean): Promise

```

Validates the form data against the SHACL shapes graph and displays validation results as icons next to the respective input fields. If `ignoreEmptyValues` is true, empty form fields will not be marked as invalid. This function is also internally called on `change` and `submit` events.



```typescript

registerPlugin(plugin: Plugin)

```

Register a [plugin](./src/plugin.ts) to customize editing/viewing certain property values. Plugins handle specific RDF predicates or `xsd:datatype`s or both. Examples: [Leaflet](./src/plugins/leaflet.ts), [Mapbox](./src/plugins/mapbox.ts), [FixedList](./src/plugins/fixed-list.ts)



```typescript

setTheme(theme: Theme)

```

Set a design theme to use for rendering. See section [Theming](#Theming).



```typescript

setClassInstanceProvider((className: string) => Promise)

```

Sets a callback function that is invoked when a SHACL property has an `sh:class` definition to retrieve class instances. See [below](#classInstanceProvider) for more information.



```typescript

setSharedShapesGraph(graph: Store)

```

Set an externally managed shapes graph to use. This improves performance When using multiple instances of `shacl-form` on the same page. Note that the shape triples need to be stored in the graph with ID `shapes` to be recognized.



## Features



### Validation



In edit mode, `` validates the constructed data graph using the library [shacl-engine](https://github.com/rdf-ext/shacl-engine) and displays validation results as icons next to the respective form fields.



### Data graph binding



`` requires only a shapes graph as input via the attribute `data-shapes` (or `data-shapes-url`) to generate an empty form and create new RDF data from the form input fields. Using the attributes `data-values` (or `data-values-url`) and `data-values-subject`, you can also bind an existing data graph to the form. The given data graph is then used to fill the form input fields.



### Viewer mode



`` not only is an RDF data editor, but can also be used as a viewer by setting attribute `data-view` and binding both, a shapes and a data graph. See the [demo](https://ulb-darmstadt.github.io/shacl-form/#viewer-mode) for an example.



### Providing additional data to the shapes graph



Apart from setting the element attributes `data-shapes` or `data-shapes-url`, there are two ways of adding RDF data to the shapes graph:

1. While parsing the triples of the shapes graph, any encountered `owl:imports` predicate that has a valid HTTP URL value will be tried to fetch with the HTTP Accept header set to all of the [supported](#formats) MIME types. A successful response will be parsed and added to the shapes graph. The [example shapes graph](https://ulb-darmstadt.github.io/shacl-form/#example) contains the following triples:

    ```

    example:Attribution

      owl:imports  ;

      sh:property [

        sh:name      "Role" ;

        sh:path      dcat:hadRole ;

        sh:class     prov:Role ;

      ] .

    ```

    In this case, the URL references an ontology which among other things defines instances of class `prov:Role` that are then used to populate the "Role" dropdown in the form.



2. The `` element has a function `setClassInstanceProvider((className: string) => Promise)` that registers a callback function which is invoked when a SHACL property has

an `sh:class` predicate. The expected return value is a (promise of a) string (e.g. in format `text/turtle`) that contains RDF class instance definitions of the given class. Instances can be defined e.g. like:

    - `example:Instance a example:Class`

    - `example:Instance a owl:NamedIndividual; skos:broader example:Class`

  

    Class hierarchies can be built using `rdfs:subClassOf` or `skos:broader`.

    

    In [this example](https://ulb-darmstadt.github.io/shacl-form/#example), the code:

  

    ```typescript

    form.setClassInstanceProvider((clazz) => { 

      if (clazz === 'http://example.org/Material') {

        return `

             a ;  "Steel".

              a ;  "Wood".

             a ;  "Alloy".

           a ;  "Plaster".

        `

      }}

    )

    ```

    returns instances of the class `http://example.org/Material` that are then used to populate the "Artwork material" dropdown in the form.



    A more realistic use case of this feature is calling some API endpoint to fetch class instance definitions from existing ontologies.



### SHACL "or" constraint



`` supports using [sh:or](https://www.w3.org/TR/shacl/#OrConstraintComponent) to let users select between different options on nodes or properties.

The [example shapes graph](https://ulb-darmstadt.github.io/shacl-form/#example) has the following triples:

```

example:Attribution

  a sh:NodeShape ;

  sh:property [

    sh:maxCount  1 ;

    sh:minCount  1 ;

    sh:path prov:agent ;

    sh:or (

      [ sh:node example:Person ; rdfs:label "Person" ]

      [ sh:node example:Organisation ; rdfs:label "Organisation" ]

    )

  ] .

```

When adding a new attribution, `` renders a dropdown to let the user select between the two options Person/Organisation. After selecting one of the options, the dropdown is replaced by the input fields of the selected node shape.



When binding an existing data graph to the form, the `sh:or` constraint is tried to be resolved depending on the respective data value:

- For RDF literals, an `sh:or` option with a matching `sh:datatype` is chosen

- For blank nodes or named nodes, the `rdf:type` of the value is tried to be matched with a node shape having a corresponding `sh:targetClass` or with a property shape having a corresponding `sh:class`. If there is no `rdf:type` but a `sh:nodeKind` of `sh:IRI`, the id of the the node is used as the value.



### SHACL shape inheritance



SHACL defines two ways of inheriting shapes: [sh:and](https://www.w3.org/TR/shacl/#AndConstraintComponent)

and [sh:node](https://www.w3.org/TR/shacl/#NodeConstraintComponent). `` supports both. In [this example](https://ulb-darmstadt.github.io/shacl-form/#example), node shape `example:ArchitectureModelDataset` extends `example:Dataset` by defining the following RDF triple:



```

example:ArchitectureModelDataset sh:node example:Dataset .

```



Properties of inherited shapes are displayed first.



### Plugins



Plugins can modify rendering of the form and add functionality to edit and view certain RDF datatypes or predicates (or a combination of both). As an example, the JavaScript of [this page](https://ulb-darmstadt.github.io/shacl-form/#example) contains the following code:

```typescript

import { LeafletPlugin } from '@ulb-darmstadt/shacl-form/plugins/leaflet.js'

const form = document.getElementById("shacl-form")

form.registerPlugin(new LeafletPlugin({ datatype: 'http://www.opengis.net/ont/geosparql#wktLiteral' }))

```

In effect, whenever a SHACL property has an `sh:datatype` of `http://www.opengis.net/ont/geosparql#wktLiteral`, the plugin is called to create the editor and/or viewer HTML elements. This specific plugin uses [Leaflet](https://leafletjs.com/) to edit or view geometry in format [well known text](http://giswiki.org/wiki/Well_Known_Text) on a map.

Custom plugins can be built by extending class [Plugin](https://github.com/ULB-Darmstadt/shacl-form/blob/main/src/plugin.ts#L40).



### Property grouping and collapsing



Properties can be grouped using [sh:group](https://www.w3.org/TR/shacl/#group) in the shapes graph. [This example](https://ulb-darmstadt.github.io/shacl-form/#example) defines a group "Physical properties" and assigns certain properties to it.



When the element attribute `data-collapse` is set, `` creates an accordion-like widget that toggles the visibility of grouped properties in order to reduce the visual complexity of the form. If the grouped properties should initially be shown, set `data-collapse="open"`.



Apart from grouped properties, all properties having an `sh:node` predicate and `sh:maxCount` != 1 are collapsed.



### Use with Solid Pods



`` can easily be integrated with [Solid Pods](https://solidproject.org/about). The output of `toRDF()` being a RDF/JS N3 Store, as explained [above](#toRDF), it can be presented to `solid-client`s `fromRdfJsDataset()` function, which converts the RDF graph into a Solid Dataset. The following example, based on Inrupt's basic [Solid Pod example](https://docs.inrupt.com/developer-tools/javascript/client-libraries/tutorial/getting-started/) shows how to merge data from a `` with a Solid data resource at `readingListDataResourceURI`:

 

```js

  // Authentication is assumed, resulting in a fetch able to read and write into the Pod

  try {

    // Get data out of the shacl-form

    const form = document.querySelector('shacl-form')



    // Extract the RDF graph from the form

    const shaclFormGraphStore = await form.toRDF()



    // Convert RDF store into a Solid dataset

    const shaclFormDataset = await fromRdfJsDataset(shaclFormGraphStore)



    // First get the current dataset

    myReadingList = await getSolidDataset(readingListDataResourceURI, { fetch: fetch })



    // get all things from the shaclFormDataset

    const shaclFormThings = getThingAll(shaclFormDataset)



    // add the things from ShaclForm to the existing set

    shaclFormThings.forEach((thing) => (myReadingList = setThing(myReadingList, thing)))



    // save the new dataset

    let savedReadingList = await saveSolidDatasetAt(readingListDataResourceURI, myReadingList, {

      fetch: fetch

    })



    // Other handling here



  } catch (err) {

    console.error(`Storing SHACL data from Form failed with error ${err}!`)

  }

```



### Theming



`` comes in 3 different bundles, each providing a specific theme. See the [demo page](https://ulb-darmstadt.github.io/shacl-form/#theming) for an example.



Theme | Import statement

--- | ---

[Default](./src/themes/default.ts) (slightly customized default browser styles) | `import '@ulb-darmstadt/shacl-form/form-default.js'`

[Bootstrap](./src/themes/bootstrap.ts) [alpha status] | `import '@ulb-darmstadt/shacl-form/form-bootstrap.js'`

[Material Design](./src/themes/material.ts) [alpha status] | `import '@ulb-darmstadt/shacl-form/form-material.js'`



Custom themes can be employed by extending class [Theme](./src/theme.ts), then calling function `setTheme()` on the `` element.