SemCom Component Specification 1.0: Draft of 16 August 2021
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.
Each SemCom component is described by a limited set of metadata predicates, prefixed with
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.
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.
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.
To be as interoperable as possible, the behavior of a SemCom component is fully specified by four
semcom-data-response. The host application should listen on the first three of these, and fire the fourth as a response.
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:
uint8array. The event types are then specified further individually:
semcom-data-read: Optionally containing a
mimefield, 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
datawith 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
datawith 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
datawith 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
successfield, and a
causefield containing the event on which it response.
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.