SemCom Component Specification 1.0: Draft of 16 August 2021

1. Introduction

SemCom aims to provide a decentralized network of registries to support the dynamic binding of semantic components in Solid data browsers. This document specifies the different parts of the SemCom ecosystem, in particular the form and behavior of the semantic components.

This specification builds on definitions of the DOM and HTML standards.

2. Component metadata

Each SemCom component is described by a limited set of metadata predicates, prefixed with http://semcom.digita.ai/voc#:

  • uri: the URL of the component itself (see section Component distribution)

  • label: a textual label by which to refer to component

  • description: a textual description of the component

  • author [*]: an author of the component

  • tag [*]: a tag by which to describe and filter the component

  • version: the version number of the component

  • latest: the boolean value indicating whether this component is the latest of it’s versions

  • shapes [*]: a URI of a data shape the component can render

Predicates with a [*] can have multiple values present within the metadata of the same component.

3. SemCom components

A SemCom component is a Web Component, i.e. a custom HTMLElement encapsulated in a Shadow DOM. In order maintain as much freedom for the component developer, and to increase interoperability with existing and future applications, further restrictions on the form of the element are limited as much as possible. Importantly, this specification does not enforce the use of any framework.

3.1. Component form

As indicated above, restrictions on the form of the element are kept to a minimum: only a single requirement of this specification pertains to the structure of the SemCom component. This requirement is that the component should have an entry attribute, which is can be set by the host application to the entry URL of the data resource that needs to be displayed and adheres to one of the data shapes for which the component is defined.

3.2. Component behavior

To be as interoperable as possible, the behavior of a SemCom component is fully specified by four CustomEvent types: semcom-data-read, semcom-data-write, semcom-data-append and semcom-data-response. The host application should listen on the first three of these, and fire the fourth as a response.

The detail payloads of each of these event types are defined by this specification. All four of them must have a uri field containing the URL of the data resource, and a type field indicating the datatype in which the resource is passed. This type can be any of the following: quads, text, json, blob or uint8array. The event types are then specified further individually:

  • semcom-data-read: Optionally containing a mime field, this event asks the host application to read data from the URI, with the given MIME type if specified, then parse the data in the correct datatype, and pass the data with a response event.

  • semcom-data-write: Containing an extra field data with data in the specified type, this event asks the host application to write the passed data to the given URI.

  • semcom-data-append: Containing an extra field data with data in the specified type, this event asks the host application to append the passed data to the given URI.

  • semcom-data-response: Containing an extra field data with data in the specified type, this event responds to any of the events above, passing the data that is actually read, written or appended back from the host application to the component. This event additionally contains a boolean success field, and a cause field containing the event on which it response.

3.3. Component distribution

Each component must be available as a single JavaScript module, served with the Content-Type text/javascript, containing all code (logic, markup and styling) necessary to render the data. Again, this specification defines no particular way of achieving this, as multiple methods, such as module bundlers, exist for this purpose.

4. SemCom nodes

Since the choice of SemCom components depends on the shape of the data, the host application must be able to decide dynamically (i.e. at runtime) which component to use. For this purpose, SemCom provides a registry API, where host applications can query for available components. This API allows for the following requests.

  • GET /component: retrieves the metadata of all components.

  • POST /component: adds the body of the request as new metadata. This endpoint is optional, i.e. read-only registries are a possibility.

  • POST /component/query: performs a query for metadata of components, based on the metadata constraints in the body. the body of the request as new metadata.

To keep the registry servers lightweight, only metadata about the components are stored (see the section on Component metadata). This metadata is stored in Solid pods. Each registry server keeps a list of such metadata storage pods of which it trusts the contents.

The registry servers behave as decentralized networks of nodes that can sync their peers, storage pods and metadata with servers they trust. For this purpose, the API also contains the following endpoints.

  • GET /peers: retrieves a JSON list of URLs of the other SemCom nodes the server trusts and syncs with.

  • GET /storage: retrieves a JSON list of URLs of the Solid storage pods the server knows.

These endpoints can be called on a regular basis by a node’s peers, in order to propagate metadata across the decentralized network.