Solid Application Interoperability Primer

Editor’s Draft,

This version:
https://solid.github.io/data-interoperability-panel/primer/
Issue Tracking:
GitHub
Inline In Spec
Editor:
elf Pavlik

Copyright © 2021 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules apply.

Abstract

Primer for the Solid interoperability.

Status of this document

1. Introduction

Write introduction

Overview

Explain visual language

2. Data

All turtle and shapetree code snippets in this primer will assume following prefixes.

@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix solid: <http://www.w3.org/ns/solid/terms#> .
@prefix interop: <http://www.w3.org/ns/solid/interop#> .
@prefix solidshapes: <https://solidshapes.example/shapes/> .
@prefix solidtrees: <https://solidshapes.example/trees/> .
@prefix ex: <https://namespace.example/> .
@prefix acme: <https://acme.example/> .
@prefix alice: <https://alice.example/> .
@prefix bob: <https://bob.example/> .
common prefixes for turtle

All ShExC code snippets will asssume

PREFIX solidshapes: <https://solidshapes.example/shapes/>
PREFIX ex: <https://namespace.example/>
common prefixes for ShExC

2.1. solidshapes.example

2.1.1. Shapes

solidshapes:ProjectShape {
  a [ ex:Project ]
}
Project shape (ShEx)
solidshapes:TaskShape {
  a [ ex:Task ] ;
  ex:inProject IRI
}
Task shape (ShEx)

2.1.2. Shape Trees

solidtrees:Project
  a shapetree:ShapeTree ;
  shapetree:expectsType shapetree:ShapeTreeResource ;
  shapetree:validatedBy solidshapes:Project ;
    shapetree:reference [
    shapetree:traverseViaReverseShapePath "@solidshapes:Task/ex:inProject" ;
    shapetree:hasShapeTree solidtrees:Task
  ] ;
  shapetree:matchesUriTemplate "{uuid}" .
Project shape tree
solidtrees:Task
  a shapetree:ShapeTree ;
  shapetree:expectsType shapetree:ShapeTreeResource ;
  shapetree:validatedBy solidshapes:Task ;
  shapetree:matchesUriTemplate "{uuid}" .
Task shape tree

2.2. acme.example

2.2.1. Data Registrations

acme:4d594c61-7cff-484a-a1d2-1f353ee4e1e7
  a interop:DataRegistration ;
  interop:registeredBy <https://garry.example/#id> ;
  interop:registeredWith <https://solidmin.example/#app> ;
  interop:registeredAt "2020-08-23T21:12:27.000Z"^^xsd:dateTime ;
  interop:registeredShapeTree solidtrees:Project ;
  interop:hasRegisteredDataInstance acme:9005ea66-fcc3-47af-b082-5da78140bc53\#project ,
                                    acme:df0aa24c-fe28-4e9f-9f35-2a9a29d63a06\#project ,
                                    acme:21270a16-f07d-417e-9d7c-274cbd8d24f0\#project .
ACME’s data registration for projects
acme:4d594c61-7cff-484a-a1d2-1f353ee4e1e7
  a interop:DataRegistration ;
  interop:registeredBy <https://garry.example/#id> ;
  interop:registeredWith <https://solidmin.example/#app> ;
  interop:registeredAt "2020-08-23T21:12:45.000Z"^^xsd:dateTime ;
  interop:registeredShapeTree solidtrees:Task ;
  interop:hasRegisteredDataInstance acme:9b982a4b-2642-496b-9990-d4464fb36771\#task ,
                                    acme:cf5d7d37-ae8e-40c1-a5d1-ef22cf228507\#task ,
                                    acme:ef55ad4d-335f-48fe-8224-c813d4649873\#task ,
                                    acme:6702961f-e74d-4fa9-991c-b95749d790cb\#task ,
                                    acme:7496fcb2-9472-4860-ae7e-c48baf9ff92f\#task ,
                                    acme:caaadc1f-affa-4fca-bd9a-98c174947cfe\#task ,
                                    acme:260ca6e2-b583-4e11-8f02-99e14638d4c1\#task .
ACME’s data registration for tasks

2.3. alice.example

2.3.1. WebID Document

alice:\#id
  a interop:Agent ;
  interop:hasAccessGrantRegistrySet alice:40c34ba8-5d85-47e5-af40-abc3e7fecdec ;
  interop:hasRemoteDataRegistrySet alice:ba4da3ec-dea4-41b2-be02-e4bf7a9477df .
Alice’s WebID document

2.3.2. Registry Sets

alice:ba4da3ec-dea4-41b2-be02-e4bf7a9477df
  a interop:RemoteDataRegistrySet ;
  interop:hasRegistry
    alice:6f6e4241-75a2-4780-9b2a-40da53082e54 .
Alice’s Remote Data Registry Set
alice:6f6e4241-75a2-4780-9b2a-40da53082e54
  a interop:RemoteDataRegistry ;
  interop:hasRegistration
    alice:33caf7be-f804-4155-a57a-92216c577bd4 .
Alice’s Remote Data Registry
alice:40c34ba8-5d85-47e5-af40-abc3e7fecdec
  a interop:AccessGrantRegistrySet ;
  interop:hasRegistry
    alice:3c7f1d03-0721-4eb1-9adf-6a8690f33b35 .
Alice’s Access Grant Registry Set
alice:3c7f1d03-0721-4eb1-9adf-6a8690f33b35
  a interop:AccessGrantRegistry ;
  interop:hasRegistration alice:6b1b6e39-75e4-44f8-84f3-104b1a8210ad .
Alice’s Access Grant Registry

2.3.3. Data Registrations

alice:773605f0-b5bf-4d46-878d-5c167eac8b5d
  a interop:DataRegistration ;
  interop:registeredBy <https://alice.example/#id> ;
  interop:registeredWith <https://solidmin.example/#app> ;
  interop:registeredAt "2020-10-17T11:42:35.000Z"^^xsd:dateTime ;
  interop:registeredShapeTree solidtrees:Project ;
  interop:hasRegisteredDataInstance alice:ccbd77ae-f769-4e07-b41f-5136501e13e7\#project .
Alice’s data registration for projects
alice:4d594c61-7cff-484a-a1d2-1f353ee4e1e7
  a interop:DataRegistration ;
  interop:registeredBy <https://alice.example/#id> ;
  interop:registeredWith <https://solidmin.example/#app> ;
  interop:registeredAt "2020-10-17T11:42:36.000Z"^^xsd:dateTime ;
  interop:registeredShapeTree solidtrees:Task ;
  interop:hasRegisteredDataInstance alice:576520a6-af5a-4cf9-8b40-8b1512b59c73\#task ,
                                    alice:106a82aa-6911-4a7e-a49b-383cbaa9da66\#task .
Alice’s data registration for tasks
alice:33caf7be-f804-4155-a57a-92216c577bd4
  a interop:RemoteDataRegistration ;
  interop:registeredBy <https://alice.example/#id> ;
  interop:registeredWith <https://jarvis.alice.example/#agent> ;
  interop:registeredAt "2020-09-05T06:15:01Z"^^xsd:dateTime ;
  interop:updatedAt "2020-09-05T06:15:01Z"^^xsd:dateTime ;
  interop:providedAt "2020-09-05T06:16:01Z"^^xsd:dateTime ;
  interop:hasDataReceipt
    alice:23dd1856-ac91-4acb-85ce-7f335057c8ae ;
  interop:hasRegistration
    acme:f201471d-b1fb-40ad-9eac-867aaf09c3e5 ;
  interop:registeredShapeTree solidtrees:Project ;
  interop:scopeOfDataGrant interop:SelectedInstances ;
  interop:accessMode acl:Read, acl:Write ;
  interop:hasRemoteDataInstance
    alice:c8d29dce-eb5b-4894-9e4a-02781dbfcba3 ,
    alice:a3859644-a71c-4a41-b253-d0cce25a0126 .
Alice’s remote data registration for projects @ acme.example
alice:c8d29dce-eb5b-4894-9e4a-02781dbfcba3
  a interop:RemoteDataInstance ;
  interop:registeredAt "2020-09-05T06:15:01Z"^^xsd:dateTime ;
  interop:updatedAt "2020-09-05T06:15:01Z"^^xsd:dateTime ;
  interop:providedAt "2020-09-05T06:16:01Z"^^xsd:dateTime ;
  interop:hasDataReceipt
    alice:23dd1856-ac91-4acb-85ce-7f335057c8ae ;
  interop:registeredShapeTree solidtrees:Project ;
  interop:accessMode acl:Read, acl:Write ;
  interop:hasRegisteredDataInstance
    acme:9005ea66-fcc3-47af-b082-5da78140bc53\#project .
Alice’s remote data instance for P1 @ acme.example
alice:a3859644-a71c-4a41-b253-d0cce25a0126
  a interop:RemoteDataInstance ;
  interop:registeredAt "2020-09-05T06:15:01Z"^^xsd:dateTime ;
  interop:updatedAt "2020-09-05T06:15:01Z"^^xsd:dateTime ;
  interop:providedAt "2020-09-05T06:16:01Z"^^xsd:dateTime ;
  interop:hasDataReceipt
    alice:23dd1856-ac91-4acb-85ce-7f335057c8ae ;
  interop:registeredShapeTree solidtrees:Project ;
  interop:accessMode acl:Read, acl:Write ;
  interop:hasRegisteredDataInstance
    acme:21270a16-f07d-417e-9d7c-274cbd8d24f0\#project .
Alice’s remote data instance for P3 @ acme.example

2.3.4. Access Grants

alice:6b1b6e39-75e4-44f8-84f3-104b1a8210ad
  a interop:AccessGrant ;
  interop:registeredBy alice:\#me ;
  interop:registeredWith <https://solidmin.example/#app> ;
  interop:registeredAt "2020-09-05T06:15:01Z"^^xsd:dateTime ;
  interop:updatedAt "2020-09-05T06:15:01Z"^^xsd:dateTime ;
  interop:hasAccessGrantSubject <#subject> ;
  interop:hasDataGrant <#project-grant>, <#task-grant> .

<#subject>
  a interop:AccessGrantSubject ;
  interop:accessByAgent alice:\#me ;
  interop:accessByApplication <https://performchart.example/#app> .

<#project-grant>
  a interop:DataGrant ;
  interop:registeredShapeTree solidtrees:Project ;
  interop:accessMode acl:Read ;
  interop:scopeOfDataGrant interop:AllInstances .

<#task-grant>
  a interop:DataGrant ;
  interop:registeredShapeTree solidtree:Task ;
  interop:accessMode acl:Read ;
  interop:scopeOfDataGrant interop:AllInstances .
Alice’s access grant to PerformChart

2.4. bob.example

2.4.1. Data Registrations

bob:0af793c1-8abc-441c-aacc-f78483b34217
  a interop:DataRegistration ;
  interop:registeredBy <https://bob.example/#id> ;
  interop:registeredWith <https://solidmin.example/#app> ;
  interop:registeredAt "2019-03-14T13:42:31.000Z"^^xsd:dateTime ;
  interop:registeredShapeTree solidtrees:Project ;
  interop:hasRegisteredDataInstance bob:e293da85-59cf-45e6-9c1c-c721cfa59893\#project .
Bob’s data registration for projects
bob:4675444a-8a4d-46e1-abfe-85147e5a9b76
  a interop:DataRegistration ;
  interop:registeredBy <https://bob.example/#id> ;
  interop:registeredWith <https://solidmin.example/#app> ;
  interop:registeredAt "2019-03-14T13:42:32.000Z"^^xsd:dateTime ;
  interop:registeredShapeTree solidtrees:Task ;
  interop:hasRegisteredDataInstance bob:17fe4de3-6c6a-4ebe-9b75-b942cfdfa087\#task ,
                                    bob:df5581b7-c047-49f8-9f34-ed8fc6570548\#task .
Bob’s data registration for tasks

2.5. performchart.example

performchart:\#app
  a interop:Application ;
  interop:applicationName "PerformChart" ;
  interop:applicationDescription
    "Creates performance statistics and visualisation for the projects you work on" ;
  interop:hasAccessNeedGroup <#access> .

<#access>
  interop:hasAccessNeed <#project> ;
  interop:hasAccessNeedOverride <#task> ;
  interop:hasAccessDecoratorIndex performchart:44430955-4844-466b-9e1b-04893d0a0d50 .

<#project>
    a interop:AccessNeed ;
    interop:registeredShapeTree solidtrees:Project ;
    interop:recursivelyAuthorize true ;
    interop:accessNecessity interop:AccessRequired ;
    interop:accessMode acl:Read .

<#task> # Override to stop recursion
    a interop:AccessNeed ;
    interop:registeredShapeTree solidtrees:Task ;
    interop:recursivelyAuthorize false ;
    interop:accessNecessity interop:AccessRequired ;
    interop:accessMode acl:Read .
PerformChart’s application profile document

Conformance

Document conventions

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]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

Conformant Algorithms

Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and abort these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm.

Conformance requirements phrased as algorithms or specific steps can be implemented in any manner, so long as the end result is equivalent. In particular, the algorithms defined in this specification are intended to be easy to understand and are not intended to be performant. Implementers are encouraged to optimize.

References

Normative References

[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119

Issues Index

Write introduction ↵
Explain visual language ↵