What would we expect to be included in service descriptions for Solid

[woutermont]

In the Matrix chat and in private conversation, I have proposed to look into service descriptions with RESTDesc as a base for interoperability. I'm absolutely not married to that idea, so I'd like to use this discussion to build understanding of what should be included in service descriptions in their most general form.

To start with, let me define the core terms, using terminology of WS-ARCH.

A Service is defined as a set of tasks (actions with a specific purpose) related to a Resource, which the Resource Owner makes available on a Resource Server for (other) Agents to access. In fact any access to a Resource is a Service being executed. This makes Services the perfect abstraction for the 'scope' of access a Client might request of a Resource Owner, and the Resource Owner might grant or deny.

A Service Description is a (machine-readable) contract defining the provided Service. For example, the service "retrieving a Turtle representation of an RDF Source" is typically defined as "a GET request to the Resource URI with Accept header 'text/turtle' will result in a response Content-Type header 'text/turtle' and a Turtle representation of the Resource encoded in the body." Different Service Description languages provide ways to encode this sentence in a machine-readable form (here is where RESTDesc comes into play, and for which WS-ARCH uses WSDL).

[woutermont]

On a most basic level, a Service Description should include what kind of requests it can handle, and what the responses to those requests will be. RESTDesc makes at least two interesting choices on that aspect:

• It uses the W3C's existing HTTP Vocabulary in RDF to describe the requests and responses. While some finer terms still seem to be missing to fully describe the messages, the vocabulary already provides a sound basis. I think this is definitely something worth using. 👍

• It uses Notation3 (N3) Rules (entailments between RDF graph patterns with variables) to define the preconditions (request parameters) and postconditions (effect on state + response). While this allows for a more lightweight notation than some other languages, I wonder whether it serves any concrete advantage to characterize Service Descriptions as entailments, rather than just one RDF graph. 🤔

[woutermont]

What would make Service Descriptions extra useful, is the ability to derive them from each other and/or nest them in each other, a bit similar to the ShapeTrees used by the current Solid Application Interoperability specification (SAI). In a more general way, Service Descriptions should allow us to express that, for example, a Triple Pattern Fragment (TPF) Service offers a broad querying mechanism, but an RO might permit a client to only use a 'subservice' of it by fixing the subject parameter. Subservices can also be used as record of a Resource Owner's limitation of authorization to a certain part of the data.

It would be interesting to look into how far such derivation and/or nesting can go, what the use cases are, what the limits, how it is easily expressed, and how easily computed ...

[woutermont]

Important for the aims of Solid is that Service Descriptions not only contain the machine-readable semantics of a Service, but also the necessary metadata to form a human-readable description of a Service, in order for Resource Owners to truly understand what they are giving access to.

A description of a JPEG image might, for example, consist of some general structure provided by the Service Description, optionally filled in with specific details like a metadata label, its location in a container hierarchy, or even a thumbnail of the image itself. On the other hand, when a Client requests access to JPEG images in general, the same Service Description might provide a description without parameters (e.g. simply "JPEG Images").

To continue on the TPF example from above: for a subservice that allows access to all triples with Alice's WebID as the subject, a description could be rendered from the template "All data about ..." provided by the TPF Service Description combined with the label found in Alices WebID, resulting in "All data about Alice."

We should look into how such description templates can best be included in Service Descriptions, and how Authorization Servers can use them to render informative access requests to the Resource Owner.