🚧Solid client protocol

This page define a Solid client-to-client standard to build DFC compliant Solid applications.

Conformance

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Introduction

This section is non-normative.

Terminology

This section is non-normative.

The Solid Client Protocol specification defines the following terms. These terms are referenced throughout this specification.

application

Refers to an application that follows this client protocol.

client protocol

The DFC Solid Cient Protocol refers to this specification: the document you are currently reading.

Namespaces

Prefix	Namespace	Description
solid	http://www.w3.org/ns/solid/terms#	Solid Terms.
dfc-b	https://www.datafoodconsortium.org#	Data Food Consortium business ontology.
dfc-f	TBD.	Data Food Consortium facets taxonomy.
dfc-m	TBD.	Data Food Consortium measures taxonomy.
dfc-pt	TBD.	DFC product types SKOS taxonomy.
dfc-t	TBD.	Data Food Consortium technical ontology.

Configuration

An application SHOULD save its settings in the user's preferences document.

In the user's preferences document, an application COULD find a link to one or several DFC dedicated solid:TypeIndex containing only registrations related to DFC resources. These type indexes can be used to reduce the parsing of general type indexes which can contain a huge amount of registrations. When existing, these DFC specific type indexes MUST be indicated with triples of the form ?preference a dfc-t:typeIndex; solid:instance ?typeIndexFile. as shown in the following example:

Example of a user's preferences file in turtle

@base <https://example.pod/username>.
@prefix solid: <http://www.w3.org/ns/solid/terms#>.
@prefix dfc-t: <TDB>.

<#types-indexes> a dfc-t:typeIndex; 
    solid:instance </datafoodconsortium/publicTypeIndex.ttl>,
        </datafoodconsortium/privateTypeIndex.ttl>.

Storage and resources

Resources MUST be expressed using the DFC ontology version 1.8 or later and taxonomies. Arities defined by the DFC ontology MUST be respected. An example dataset could be found at https://github.com/datafoodconsortium/solid-dataset-example.

An application MUST let users to choose where they want to store data on their POD(s). Resources location MUST be defined in one or several solid:TypeIndex. Each used DFC resource or container MUST be registered in these type indexes. See the TypeIndex section for more details.

When users don't know or don't want to choose where to save their data, an application SHOULD propose a default location like /datafoodconsortium/ as the root LDP container for DFC data. Following the tree structure defined in the example dataset is RECOMMENDED.

Indexing

Applications MUST fill and keep updated several indexes in order to allow quick searching of piece of information. All the following indexes MUST be supported by applications and MUST be updated whenever a DFC data is created, edited or deleted.

The application who creates, edit or delete data MUST update all the appropriate indexes. While updating indexes is its responsibility, an application can delegate that work to some agent(s).

Orders

Indexing the year and month of orders

This index MUST be registered in one or several type indexes for the class dfc-t:OrderIndex. All dfc-b:Order SHOULD be indexed.

Such an index can be used to retrieve orders for a certain period of time like a year or a month of a year.

Example of a dfc-t:OrderIndex in turtle

@base <https://example.pod/username/datafoodconsortium>.
@prefix solid: <http://www.w3.org/ns/solid/terms#>.
@prefix dfc-b: <https://www.datafoodconsortium.org#>.
@prefix dfc-m: <TBD>.
@prefix index: <TBD>.
@prefix dfc-t: <TBD>.

<>
    a index:Index, dfc-t:OrderIndex;
    a solid:ListedDocument;
    
<#1>
    a index:Registration;
    index:year 2022;
    index:month 12;
    solid:instance </orders/order2.ttl>.
    
<#2>
    a index:Registration;
    index:year 2022;
    index:month 11;
    solid:instance </orders/order1.ttl>.

Persons

Indexing the first letter of the family name

This index MUST be registered in one or several type indexes for the class dfc-t:PersonIndex. All dfc-b:Person SHOULD be indexed. It MUST contain a registration for each first symbol used in the family name of all the persons.

Such an index can be used to display quickly a person when the user types the beginning of a family name.

Example of a dfc-t:PersonIndex in turtle

@base <https://example.pod/username/datafoodconsortium>.
@prefix solid: <http://www.w3.org/ns/solid/terms#>.
@prefix dfc-b: <https://www.datafoodconsortium.org#>.
@prefix index: <TDB>.
@prefix dfc-t: <TBD>.

<>
    a index:Index, dfc-t:PersonIndex;
    a solid:ListedDocument;
    index:forProperty dfc-b:familyName.

# This is indexing persons with a family name starting with the letter "a".
<#ab09fd> a index:Registration;
    index:strstarts "a";
    solid:instance  </agents/persons/person32.ttl>, </agents/persons/person12.ttl>.

# This is indexing persons with a family name starting with the letter "b".
<#zx45yh> a index:Registration;
    index:strstarts "b";
    solid:instance  </agents/persons/person56.ttl>, </agents/persons/person78.ttl>.

# This is indexing persons with a family name starting with the letter "z".
<#sk17vb> a index:Registration;
    index:strstarts "z";
    solid:instance  </agents/persons/person2.ttl>, </agents/persons/person63.ttl>.

Product types

Indexing the product types contained in a catalog

This index MUST be registered in one or several type indexes for the class dfc-t:ProductTypeIndex. All dfc-b:CatalogItem SHOULD be indexed. It MUST contain registrations mentioning product type.

This index MUST contain registrations for inferred product types. For instance, if a registration is created for the dfc-pt:heirloom-tomato product type, a registration MUST also be created for both the dfc-pt:tomato and the dfc-pt:vegetable product types.

Such an index can be used to quickly find all the catalog items referencing a product of a given type. For instance, it can be used to find all the tomatoes listed in a catalog.

Example of a dfc-t:ProductTypeIndex in turtle

@base <https://example.pod/username/datafoodconsortium/>.
@prefix solid: <http://www.w3.org/ns/solid/terms#>.
@prefix dfc-pt: <https://www.datafoodconsortium.org/productTypes#>.
@prefix index: <TBD>.
@prefix dfc-t: <TBD>.
@prefix : <productTypeIndex>.

<#>
    a index:Index, dfc-t:ProductTypeIndex;
    a solid:ListedDocument.

<#artichokes> a index:Registration;
    solid:instance <catalogs/default/catalog#artichoke>;
    index:mentions dfc-pt:artichoke.

<#round-tomatoes> a index:Registration;
    solid:instance <catalogs/default/catalog#round-tomato>;
    index:mentions dfc-pt:round-tomato.
    
<#cherry-tomatoes> a index:Registration;
    solid:instance <catalogs/default/catalog#cherry-tomato>;
    index:mentions dfc-pt:cherry-tomato.

# Inferred registration
<#tomatoes> a index:Registration;
    solid:instance 
        <catalogs/default/catalog#round-tomato>,
        <catalogs/default/catalog#cherry-tomato>;
    index:mentions dfc-pt:tomato.

# Inferred registration
<#vegetables> a index:Registration;
    solid:instance 
        <catalogs/default/catalog#artichoke>,
        <catalogs/default/catalog#round-tomato>,
        <catalogs/default/catalog#cherry-tomato>;
    index:mentions dfc-pt:vegetable.

TypeIndex

Applications MUST advertise their DFC resources, containers and indexes in one or several solid:TypeIndex.

Example of a type index in turtle

@base <https://example.pod/username/datafoodconsortium>.
@prefix solid: <http://www.w3.org/ns/solid/terms#>.
@prefix dfc-b: <https://www.datafoodconsortium.org#>.
@prefix index: <TBD>.

<>
    a solid:TypeIndex;
    a solid:ListedDocument.

<#addresses> a solid:TypeRegistration;
    solid:forClass dfc-b:Address;
    solid:instanceContainer </addresses/>.
    
<#persons> a solid:TypeRegistration;
    solid:forClass dfc-b:Person;
    solid:instanceContainer </agents/person/>.
    
<#enterprises> a solid:TypeRegistration;
    solid:forClass dfc-b:Enterprise;
    solid:instanceContainer </agents/enterprises/>.
    
<#customer-categories> a solid:TypeRegistration;
    solid:forClass dfc-b:CustomerCategory;
    solid:instance </agents/customer-categories.ttl>.
    
<#catalogs> a solid:TypeRegistration;
    solid:forClass dfc-b:Catalog;
    solid:instanceContainer </catalogs/>.
    
# Every catalog MUST be registered
<#catalog1> a solid:TypeRegistration;
    solid:forClass dfc-b:Catalog;
    solid:instance </catalogs/default/catalog.ttl>.
    
<#functional-products> a solid:TypeRegistration;
    solid:forClass dfc-b:FunctionalProduct;
    solid:instanceContainer </defined-products/functional-products/>.
    
<#supplied-products> a solid:TypeRegistration;
    solid:forClass dfc-b:SuppliedProduct;
    solid:instanceContainer </defined-products/supplied-products/>.
    
<#technical-products> a solid:TypeRegistration;
    solid:forClass dfc-b:TechnicalProduct;
    solid:instanceContainer </defined-products/technical-products/>.
    
<#orders> a solid:TypeRegistration;
    solid:forClass dfc-b:Order;
    solid:instanceContainer </orders/>.
    
<#sale-sessions> a solid:TypeRegistration;
    solid:forClass dfc-b:SaleSession;
    solid:instanceContainer </sale-sessions/>.
    
<#person-index> a solid:TypeRegistration;
    solid:forClass index:PersonIndex;
    solid:instance </agents/persons/index0.ttl>.
    
<#product-type-index> a solid:TypeRegistration;
    solid:forClass index:ProductTypeIndex;
    solid:instance </catalogs/default/index0.ttl>.

<#order-index> a solid:TypeRegistration;
    solid:forClass index:OrderIndex;
    solid:instance </orders/index0.ttl>.

Paging and sorting

This section defines how data is paged and sorted.

Access rights

By default all resources are only accessible to the owner of the POD (private).

When a new dfc-b:CatalogItem is created, it inherits the access rights of its parent dfc-b:Catalog.

Notifications

When data is created, changed or deleted, applications MUST send a ActivityPub notification.

Error codes

The following table lists the different errors that can occur in applications. When an error happens, applications SHOULD display the error code and the "user description". Applications SHOULD also display the "technical description" if any. User descriptions are intended to provide clear and easy to understand reason(s) about what caused the error so users may find a way to solve the issue by themselves.

Code	User description	Technical description
404		Profile document not found.
		Invalid profile document.
404		Type indexes not found.
		Invalid Type Index.

Revisions and automated backups

Should we be able to automatically backup the storage?

Encryption

Appendixes