Skip to main content

Semantic Data Provider

Installation​

npm install @semapps/semantic-data-provider

Usage​

import { Admin } from 'react-admin';
import { dataProvider, httpClient } from '@semapps/semantic-data-provider';

const App = () => (
  <Admin
    dataProvider={dataProvider({
      httpClient,
      dataServers: { ... },
      resources: { ... },
      ontologies: { ... },
      jsonContext: 'http://localhost:3000/context.json',
      returnFailedResources: false
    })}
  >
    <Resource name="Project" ... />
    <Resource name="Organization" ... />
  </Admin>
);

The semantic data provider rely on two important configuration:

  • The Data Servers, which describes the servers to which we want to connect and what they contain.
  • The Data Model, which describes how we want the data to be displayed in React-Admin.

Settings​

httpClient​

HTTP client used to fetch data. Same type as the fetchJson utility of React-Admin.

We recommend to use the httpClient exported from the @semapps/semantic-data-provider package.

dataServers​

See the Data servers page.

resources​

See the Data model page.

ontologies​

List of ontologies used to format or select SPARQL data. Format:

const ontologies = [
  {
    prefix: 'rdf',
    url: 'http://www.w3.org/1999/02/22-rdf-syntax-ns#'
  },
  {
    prefix: 'ldp',
    url: 'http://www.w3.org/ns/ldp#'
  }
];

jsonContext​

All SPARQL results returned will be framed with this context.

If it is not set, the ontologies set above will be used.

returnFailedResources​

If true, the getMany method will not fail completely if one resource is missing.

Missing resources will be returned with their id and _error: true.

Filters​

When using React-Admin filters, in the List components or the ReferenceArrayInput, there are special keywords that you can use:

_predicates​

Return only the given predicates instead of the full resource.

For example, { _predicates: ['foaf:name']} will return only the name of a list of users.

Note: The @type is always returned because it is needed by React-Admin.

_servers​

Select the data servers that you want to query, bypassing the config in the data model.

You can use the server keys or special keywords.

blankNodes​

Choose the blank nodes you want to dereference, bypassing the config in the data model or the VOID endpoint.

For example, { blankNodes: [] } will not dereference any blank nodes for the given resources.

This is useful if you don't need the values of the blank nodes and want to increase performances.

q​

Do a full-text search on the resources.

For example, { q: "sem" } will return all resources with the characters "sem" in string-types values.

sparqlWhere​

Allow to make advanced search by providing a SPARQL.js-formatted array that will be appended to the WHERE query.

Here's an example to fetch ActivityStreams events after a given date:

{
  sparqlWhere: [
    {
      type: 'bgp',
      triples: [
        {
          subject: { termType: 'Variable', value: 's1' },
          predicate: { termType: 'NameNode', value: 'https://www.w3.org/ns/activitystreams#startTime' },
          object: { termType: 'Variable', value: 'startTime' }
        }
      ]
    },
    {
      type: 'filter',
      expression: {
        type: 'operation',
        operator: '>',
        args: [
          {
            termType: 'Variable',
            value: 'startTime'
          },
          {
            termType: 'Literal',
            datatype: {
              termType: 'NamedNode',
              value: 'http://www.w3.org/2001/XMLSchema#dateTime'
            },
            value: '2022-11-17T10:20:13+05:30'
          }
        ]
      }
    }
  ];
}

Note: In the above example, the variable s1 is the URI of a LDP resource.

Custom methods​

In addition to regular React-Admin methods, we provide custom methods that are specific to linked data. These can be accessed with the useDataProvider hook.

patch​

Patch a resource with a SPARQL-Update (application/sparql-update) operation.

Parameters​

PropertyTypeDefaultDescription
resourceIdStringrequiredReact-Admin resource ID
params.idStringrequiredURI of the resource to patch
params.triplesToAdd[Quad]Triples to insert, formatted with the RDFJS data model
params.triplesToRemove[Quad]Triples to delete, formatted with the RDFJS data model

refreshConfig​

Refresh the dymamically loaded config (VOID endpoint and, for Pods, the user config)

Hooks​

useContainers​

Returns a list of containers linked with a given resource.

const containers = useContainers(resourceId, serverKeys);

Parameters​

PropertyTypeDefaultDescription
resourceIdStringrequiredReact-Admin resource ID
serverKeysArray or String"@all"The servers where the containers are

Return value​

Array of containers URIs.

useCreateContainer​

Get the URI of the container where to create a new resource.

const createContainerUri = useCreateContainer(resourceId);

Parameters​

PropertyTypeDefaultDescription
resourceIdStringrequiredReact-Admin resource ID

Return value​

URI of the container where to create a new resource.

useCreateContainerUri​

Get the URI of the container where to create a new resource.

const getContainerUri = useCreateContainer();
const createContainerUri = getContainerUri(resourceId);

Return value​

Function to get the URI of the container where to create a new resource

PropertyTypeDefaultDescription
resourceIdStringrequiredReact-Admin resource ID

useDataModel​

Get the data model config of the given resource, including data fetched through VoID endpoints.

const dataModel = useDataModel(resourceId);

Parameters​

PropertyTypeDefaultDescription
resourceIdStringrequiredReact-Admin resource ID

Return value​

The data model config of the given resource.

useDataModels​

Get the data model config of all the resources, including data fetched through VoID endpoints.

const dataModel = useDataModels();

useDataServers​

Get the data servers config, including data fetched through VoID endpoints.

const dataServers = useDataServers();

Utilities​

getOrCreateWsChannel​

This function adheres to the Solid Notification Protocol, specifically the WebSocketChannel2023 specification. It creates a WebSocket that conforms to this specification.

Parameters​

Param PositionPropertyTypeDefaultDescription
1fetchFunctionrequiredA React Admin fetch function. You can obtain it using const { fetch } = useDataProvider().
2resourceUristringrequiredThe URI of the resource to subscribe to.
3optionsobjectOptions to pass to createSolidNotificationChannel if the channel does not exist yet. Refer to the documentation of the features in the spec for more details. See CreateSolidChannelOptions.

CreateSolidChannelOptions Interface​

PropertyTypeDefaultDescription
typestringWebSocketChannel2023The type of channel. The default and only supported option is WebSocketChannel2023.
closeAfternumberTime in milliseconds after which the channel should close.
startInnumberTime in milliseconds to wait before starting the channel.
startAtstring (ISO 8601)ISO 8601 timestamp indicating when to start the channel.
endAtstring (ISO 8601)ISO 8601 timestamp indicating when to end the channel.
ratenumberThe rate in milliseconds at which notifications should be sent at most.

createWsChannel​

This function operates similarly to getOrCreateWsChannel but always creates a new channel, even if a channel for the same resource (but potentially with different options) is already open. The newly created channel is not registered in the cache used by getOrCreateWsChannel.

createSolidNotificationChannel​

This function is used internally by getOrCreateWsChannel and createWsChannel to create a WebSocket channel object conforming to the Solid Notification Protocol.