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 shapetree: <http://www.w3.org/ns/shapetree#> .
# Fictional
@prefix solidshapes: <https://solidshapes.example/shapes/> .
@prefix solidtrees: <https://solidshapes.example/trees/> .
@prefix pm: <https://vocab.example/project-management/> .
@prefix tbd: <https://tbd.example/> .
# ACME
@prefix acme: <https://acme.example/> .
@prefix acme-rnd: <https://rnd.acme.example/> .
@prefix acme-finance: <https://finance.acme.example/> .
# Alice
@prefix alice: <https://alice.example/> .
@prefix alice-auth: <https://auth.alice.example/> .
@prefix alice-pro: <https://pro.alice.example/> .
@prefix alice-home: <https://home.alice.example/> .
# Bob
@prefix bob: <https://bob.example/> .
common prefixes for turtle
All ShExC code snippets will asssume
PREFIX xsd : <http://www.w3.org/2001/XMLSchema#>
PREFIX rdfs : <http://www.w3.org/2000/01/rdf-schema#>
PREFIX solidshapes : <https://solidshapes.example/shapes/>
PREFIX tbd : <https://tbd.example/>
PREFIX pm : <https://vocab.example/project-management/>
common prefixes for ShExC
2.1. solidshapes.example
2.1.1. Shapes
solidshapes : ProjectShape {
a [ pm : Project ] ;
rdfs : label xsd : string ;
tbd : hasReferencesList @ <#TaskReferencesList> ;
tbd : hasReferencesList @ <#MilestoneReferencesList>
}
<#TaskReferencesList> {
a [ tbd : ReferencesList ] ;
tbd : referencesOf @ solidshapes : ProjectShape ;
tbd : referenceShapePath [ "@solidshapes:Project/pm:hasTask/@solidshapes:Task" ]
}
<#MilestoneReferencesList> {
a [ tbd : ReferencesList ] ;
tbd : referencesOf @ solidshapes : MilestoneShape ;
tbd : referenceShapePath [ "@solidshapes:Project/pm:hasMilestone/@solidshapes:Milestone" ]
}
Project shape (ShEx)
solidshapes : TaskShape {
a [ pm : Task ] ;
rdfs : label xsd : string
}
Task shape (ShEx)
2.1.2. Shape Trees
solidtrees : Project
a shapetree : ShapeTree ;
shapetree : expectsType shapetree : ShapeTreeResource ;
shapetree : validatedBy solidshapes : Project ;
shapetree : references urn : uuid:54b5e4f6-c6b5-4c9a-b885-cbf69d08370d .
urn : uuid:54b5e4f6-c6b5-4c9a-b885-cbf69d08370d
shapetree : hasShapeTree solidtrees : Task ;
shapetree : traverseViaPath "@solidshapes:Project/pm:hasTask" .
Project shape tree
solidtrees : Task
a shapetree : ShapeTree ;
shapetree : expectsType shapetree : ShapeTreeResource ;
shapetree : validatedBy solidshapes : Task .
Task shape tree
2.2. acme.example
2.2.1. Data Registrations
Snippet below needs to be updated
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
Snippet below needs to be updated
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
Snippet below needs to be updated
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
Snippet below needs to be updated
alice : ba4da3ec-dea4-41b2-be02-e4bf7a9477df
a interop : RemoteDataRegistrySet ;
interop : hasRegistry
alice : 6f6e4241-75a2-4780-9b2a-40da53082e54 .
Alice’s Remote Data Registry Set
Snippet below needs to be updated
alice : 6f6e4241-75a2-4780-9b2a-40da53082e54
a interop : RemoteDataRegistry ;
interop : hasRegistration
alice : 33caf7be-f804-4155-a57a-92216c577bd4 .
Alice’s Remote Data Registry
Snippet below needs to be updated
alice : 40c34ba8-5d85-47e5-af40-abc3e7fecdec
a interop : AccessGrantRegistrySet ;
interop : hasRegistry
alice : 3c7f1d03-0721-4eb1-9adf-6a8690f33b35 .
Alice’s Access Grant Registry Set
Snippet below needs to be updated
alice : 3c7f1d03-0721-4eb1-9adf-6a8690f33b35
a interop : AccessGrantRegistry ;
interop : hasRegistration alice : 6b1b6e39-75e4-44f8-84f3-104b1a8210ad .
Alice’s Access Grant Registry
2.4. pro.alice.example
2.4.1. Data Registry
alice-pro : 71e96aaa-f3dc-4263-97d6-a5b4c83524cb
a interop : DataRegistry ;
interop : hasDataRegistration
alice-pro : 773605f0-b5bf-4d46-878d-5c167eac8b5d ,
alice-pro : 4d594c61-7cff-484a-a1d2-1f353ee4e1e7 .
Alice’s pro data registry
2.4.2. Data Registrations
alice-pro : 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 ;
ldp : contains
alice-pro : ccbd77ae-f769-4e07-b41f-5136501e13e7 ,
alice-pro : 7a130c38-668a-4775-821a-08b38f2306fb .
Alice’s data registration for pro projects
alice-pro : 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 ;
ldp : contains
alice-pro : 576520a6-af5a-4cf9-8b40-8b1512b59c73 ,
alice-pro : 106a82aa-6911-4a7e-a49b-383cbaa9da66 ,
alice-pro : 4d713903-d114-4890-a87c-eaed50c33e5e ,
alice-pro : 210cf13a-4082-487f-ab2b-ad54edb234a0 .
Alice’s data registration for pro tasks
2.4.3. Data Instances
alice-pro : ccbd77ae-f769-4e07-b41f-5136501e13e7\#project
a pm : Project ;
rdfs : label "P-Ap-1" ;
tbd : hasReferenceList alice-pro : 5db9103b-392c-41a4-b823-100c213e24ff .
alice-pro : 5db9103b-392c-41a4-b823-100c213e24ff
tbd : referenceShapePath "@solidshapes:Project/pm:hasTask/@solidshapes:Task" .
Alice’s pro project 1
alice-pro : 5db9103b-392c-41a4-b823-100c213e24ff
a tbd : ReferencesList ;
tbd : referencesOf alice-pro : ccbd77ae-f769-4e07-b41f-5136501e13e7\#project ;
tbd : referenceShapePath "@solidshapes:Project/pm:hasTask/@solidshapes:Task" .
alice-pro : ccbd77ae-f769-4e07-b41f-5136501e13e7\#project
pm : hasTask
alice-pro : 576520a6-af5a-4cf9-8b40-8b1512b59c73\#task ,
alice-pro : 106a82aa-6911-4a7e-a49b-383cbaa9da66\#task .
Alice’s pro project 1 reference list for tasks
alice-pro : 7a130c38-668a-4775-821a-08b38f2306fb\#project
a pm : Project ;
rdfs : label "P-Ap-2" ;
tbd : hasReferenceList alice-pro : aa97cee2-e698-4972-8f1c-0acf909f1377 .
alice-pro : aa97cee2-e698-4972-8f1c-0acf909f1377
tbd : referenceShapePath "@solidshapes:Project/pm:hasTask/@solidshapes:Task" .
Alice’s pro project 2
alice-pro : aa97cee2-e698-4972-8f1c-0acf909f1377
a tbd : ReferencesList ;
tbd : referencesOf alice-pro : 7a130c38-668a-4775-821a-08b38f2306fb\#project ;
tbd : referenceShapePath "@solidshapes:Project/pm:hasTask/@solidshapes:Task" .
alice-pro : 7a130c38-668a-4775-821a-08b38f2306fb\#project
pm : hasTask
alice-pro : 4d713903-d114-4890-a87c-eaed50c33e5e\#task .
Alice’s pro project 2 reference list for tasks
alice-pro : 576520a6-af5a-4cf9-8b40-8b1512b59c73\#task
a pm : Task ;
rdfs : label "T-Ap-1" .
Alice’s pro task 1
alice-pro : 106a82aa-6911-4a7e-a49b-383cbaa9da66\#task
a pm : Task ;
rdfs : label "T-Ap-2" .
Alice’s pro task 2
alice-pro : 4d713903-d114-4890-a87c-eaed50c33e5e\#task
a pm : Task ;
rdfs : label "T-Ap-3" .
Alice’s pro task 3
alice-pro : 210cf13a-4082-487f-ab2b-ad54edb234a0\#task
a pm : Task ;
rdfs : label "T-Ap-4" .
Alice’s pro task 4
2.5. home.alice.example
2.5.1. Data Registry
alice-home : 2d3d97b4-a26d-434e-afa2-e3bc8e8e2b56
a interop : DataRegistry ;
interop : hasDataRegistration
alice-home : f6ccd3a4-45ea-4f98-8a36-98eac92a6720 ,
alice-home : 92f43be4-d12c-4ca3-9bd6-c18e83167b2f .
Alice’s home data registry
2.5.2. Data Registrations
alice-home : f6ccd3a4-45ea-4f98-8a36-98eac92a6720
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 ;
ldp : contains
alice-home : 0fd3daa3-dd6b-4484-826b-9ebaef099241 .
Alice’s data registration for home projects
alice-home : 92f43be4-d12c-4ca3-9bd6-c18e83167b2f
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 ;
ldp : contains
alice-home : f950bae5-247c-49b2-a537-b12cda8d5758 ,
alice-home : 46fea403-8605-473b-a9a1-a86f50fb1633 ,
alice-home : 72eb1958-5ad1-4268-96cb-739a71592cc0 .
Alice’s data registration for home tasks
2.5.3. Data Instances
alice-home : 0fd3daa3-dd6b-4484-826b-9ebaef099241\#project
a pm : Project ;
rdfs : label "P-Ah-1" ;
tbd : hasReferenceList alice-home : 11f5ee6e-8ccf-4a70-96a8-f5174aaf9a27 .
alice-home : 11f5ee6e-8ccf-4a70-96a8-f5174aaf9a27
tbd : referenceShapePath "@solidshapes:Project/pm:hasTask/@solidshapes:Task" .
Alice’s home project 1
alice-home : 11f5ee6e-8ccf-4a70-96a8-f5174aaf9a27
a tbd : ReferencesList ;
tbd : referencesOf alice-home : 0fd3daa3-dd6b-4484-826b-9ebaef099241\#project ;
tbd : referenceShapePath "@solidshapes:Project/pm:hasTask/@solidshapes:Task" .
alice-home : 0fd3daa3-dd6b-4484-826b-9ebaef099241\#project
pm : hasTask
alice-home : f950bae5-247c-49b2-a537-b12cda8d5758\#task ,
alice-home : 46fea403-8605-473b-a9a1-a86f50fb1633\#task .
Alice’s home project 1 reference list for tasks
alice-home : f950bae5-247c-49b2-a537-b12cda8d5758\#task
a pm : Task ;
rdfs : label "T-Ah-1" .
Alice’s home task 1
alice-home : 46fea403-8605-473b-a9a1-a86f50fb1633\#task
a pm : Task ;
rdfs : label "T-Ah-2" .
Alice’s home task 2
alice-home : 72eb1958-5ad1-4268-96cb-739a71592cc0\#task
a pm : Task ;
rdfs : label "T-Ah-3" .
Alice’s home task 3
2.5.4. Remote Data Registrations
Snippet below needs to be updated
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
Snippet below needs to be updated
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
Snippet below needs to be updated
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.5.5. Access Grants
Snippet below needs to be updated
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.6. bob.example
2.6.1. Data Registrations
Snippet below needs to be updated
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
Snippet below needs to be updated
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
Snippet below needs to be updated
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
2.8. Sequence diagrams
2.8.1. Combined OIDC Provider and Authorization Agent
2.8.1.1. Authorization Agent stores Registrations and Grants
2.8.1.2. Authorization Agent gets Registrations and Grants from Storage
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.
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.