From 8a2558d18dece4882202d863782961827acf86c3 Mon Sep 17 00:00:00 2001 From: Pat McBennett Date: Wed, 3 Feb 2021 10:25:19 +0000 Subject: [PATCH 01/20] Update person.shex Just some comments for discussion - it would be nice to be able to share this file (with explanatory Turtle perhaps) with external parties who may be looking at modelling these ideas using Upper/Mid-Level Ontologies, but it would need some clarifications first I think... (and comments explaining 'missing' terms, etc.) --- shapes/contacts/person.shex | 28 ++++++++++++++++++++++++---- 1 file changed, 24 insertions(+), 4 deletions(-) diff --git a/shapes/contacts/person.shex b/shapes/contacts/person.shex index df04fb05..cdc29c5f 100644 --- a/shapes/contacts/person.shex +++ b/shapes/contacts/person.shex @@ -1,18 +1,24 @@ PREFIX vcard: PREFIX xsd: PREFIX owl: -PREFIX dc: +# PREFIX dc: +PREFIX dcterms: PREFIX rdf: -# We should store the preferred WebId for each person, since sameAs can be multiple WebIds +# We should store the preferred WebID for each person, since owl:sameAs can be multiple WebIDs. vcard:Individual { vcard:fn xsd:string {1} ; - vcard:inAddressBook vcard:AddressBook + ; + + # This is intended to refer to the Individual's WebIDs, + # or other 'types', such as...? vcard:url vcard:WebId {1}; + + # What is this intended to refer to? vcard:hasUID xsd:string ? ; + vcard:hasName xsd:string ? ; # structured name - vcard:hasPhoto dc:Image * ; + vcard:hasPhoto dcterms:Image * ; vcard:hasRelated vcard:RelatedType * ; vcard:hasAddress vcard:Address * ; vcard:bday xsd:date ? ; @@ -22,8 +28,22 @@ vcard:Individual { vcard:role xsd:string ? ; vcard:title xsd:string ? ; vcard:note xsd:string ? ; + + # These terms don't exist in vCard yet... + vcard:inAddressBook vcard:AddressBook + ; } +# This term doesn't exist in vCard yet... +# Big question - SHOULD something as fundamental as WebID be defined in vCard? +# +# An example of usage (in Turtle) showing the relation with 'vcard:url' +# might be really useful here - for example, is this correct...? +# a vcard:Individual ; +# vcard:url . +# +# a vcard:WebID ; +# vcard:value "????"^^xsd:string . +# vcard:WebId { vcard:value xsd:string {1}; } From 318e01cd51a01269ff8677e40557deb53220079e Mon Sep 17 00:00:00 2001 From: Arne Hassel Date: Thu, 4 Feb 2021 07:42:17 +0100 Subject: [PATCH 02/20] Adding comments to document shapes Should make it easier to understand each shape and their relationship between each other --- shapes/bookmarks/bookmark.shex | 3 ++ shapes/contacts/address-book.shex | 13 ++++++++ shapes/contacts/group-index.shex | 19 ++++++++++-- shapes/contacts/group.shex | 13 ++++++++ shapes/contacts/people-index.shex | 19 ++++++++++-- shapes/contacts/person.shex | 50 +++++++++++++++---------------- 6 files changed, 87 insertions(+), 30 deletions(-) diff --git a/shapes/bookmarks/bookmark.shex b/shapes/bookmarks/bookmark.shex index 338540f5..3ff9a1ca 100644 --- a/shapes/bookmarks/bookmark.shex +++ b/shapes/bookmarks/bookmark.shex @@ -3,6 +3,9 @@ PREFIX foaf: PREFIX terms: PREFIX xsd: +# This shape describes some the information we store a bookmark. The +# resource it is used describes multiple bookmarks. + bookmark:Bookmark { terms:created xsd:dateTime {1} ; terms:title xsd:string {1} ; diff --git a/shapes/contacts/address-book.shex b/shapes/contacts/address-book.shex index abd19a36..915b54d8 100644 --- a/shapes/contacts/address-book.shex +++ b/shapes/contacts/address-book.shex @@ -3,9 +3,22 @@ PREFIX dc: PREFIX vcard: PREFIX xsd: +# This shape describes some of the information we store for an address book. The +# resource it is used for is to describe a single address book. We use the id +# "#this" to refer to the subject of the address book. + +# This model is originally developed as part of the +# SolidOS/Data Browser project, and we strive to keep it interoperable with +# their work. Some custom terms have been introduced to vocabularies we think +# they could belong to (e.g. vcard:nameEmailIndex). We'll make a note of the +# custom term when used. + +# vcard:AddressBook is a custom class vcard:AddressBook { dc:title xsd:string {1} ; + # vcard:nameEmailIndex is a custom term vcard:nameEmailIndex IRI {1} ; + # vcard:groupIndex is a custom term vcard:groupIndex IRI {1} ; acl:owner IRI + } diff --git a/shapes/contacts/group-index.shex b/shapes/contacts/group-index.shex index 29c3c96f..fa15f6fe 100644 --- a/shapes/contacts/group-index.shex +++ b/shapes/contacts/group-index.shex @@ -1,7 +1,20 @@ PREFIX vcard: -PREFIX xsd: +PREFIX xsd: + +# This shape describes part of the information we store when adding a group to +# an address book. The resource it is used for is an index of groups. There will +# be multiple groups added in this resource, and each referring to the group +# resource where there are more information on the group (e.g. members). + +# This model is originally developed as part of the +# SolidOS/Data Browser project, and we strive to keep it interoperable with +# their work. Some custom terms have been introduced to vocabularies we think +# they could belong to (e.g. vcard:includesGroup). We'll make a note of the +# custom term when used. vcard:Group { - vcard:fn xsd:string {1} ; - ^ vcard:includesGroup vcard:AddressBook ; + vcard:fn xsd:string {1} ; + # vcard:includesGroup is a custom term + # vcard:AddressBook is a custom class + ^ vcard:includesGroup vcard:AddressBook ; } diff --git a/shapes/contacts/group.shex b/shapes/contacts/group.shex index 8fda45bd..f6db9b18 100644 --- a/shapes/contacts/group.shex +++ b/shapes/contacts/group.shex @@ -1,9 +1,22 @@ PREFIX vcard: PREFIX xsd: +# This shape describes some of the information we store when adding a group to +# an address book. The resource it is used for is to describe the group itself +# (meaning the resource should only contain one group). We use the id "#this" +# to refer to the subject of the group. + +# This model is originally developed as part of the +# SolidOS/Data Browser project, and we strive to keep it interoperable with +# their work. Some custom terms have been introduced to vocabularies we think +# they could belong to (e.g. vcard:includesGroup). We'll make a note of the +# custom term when used. + vcard:Group { vcard:fn xsd:string {1} ; vcard:note xsd:string ? ; vcard:hasMember vcard:Individual * OR vcard:Organization * ; + # vcard:includesGroup is a custom term + # vcard:AddressBook is a custom class ^vcard:includesGroup vcard:AddressBook } diff --git a/shapes/contacts/people-index.shex b/shapes/contacts/people-index.shex index 1821de42..01ef18c1 100644 --- a/shapes/contacts/people-index.shex +++ b/shapes/contacts/people-index.shex @@ -1,7 +1,22 @@ PREFIX vcard: PREFIX xsd: +# This shape describes part of the information we store when adding a person to +# an address book. The resource it is used for is an index of people. There will +# be multiple people added in this resource, and each referring to the person +# resource where there are more information on the person (e.g. photo, email, +# etc). + +# This model is originally developed as part of the +# SolidOS/Data Browser project, and we strive to keep it interoperable with +# their work. Some custom terms have been introduced to vocabularies we think +# they could belong to (e.g. vcard:inAddressBook). We'll make a note of the +# custom term when used. + vcard:Individual { - vcard:fn xsd:string {1} ; - vcard:inAddressBook vcard:AddressBook ? + vcard:fn xsd:string {1} ; + + # vcard:inAddressBook is a custom term + # vcard:AddressBook is a custom class + vcard:inAddressBook vcard:AddressBook ? } diff --git a/shapes/contacts/person.shex b/shapes/contacts/person.shex index cdc29c5f..cad4605d 100644 --- a/shapes/contacts/person.shex +++ b/shapes/contacts/person.shex @@ -1,22 +1,28 @@ -PREFIX vcard: -PREFIX xsd: -PREFIX owl: -# PREFIX dc: +PREFIX vcard: +PREFIX xsd: +PREFIX owl: PREFIX dcterms: -PREFIX rdf: +PREFIX rdf: -# We should store the preferred WebID for each person, since owl:sameAs can be multiple WebIDs. +# This shape describes the information we store when adding a person to an +# address book. The resource it is used for represents a local copy of a +# person's profile. We use the id "#this" to refer to the subject of the person. + +# This model is originally developed as part of the SolidOS/Data +# Browser project, and we strive to keep it interoperable with their work. +# Some custom terms have been introduced to vocabularies we think they could +# belong to (e.g. vcard:inAddressBook). We'll make a note of the custom term +# when used. vcard:Individual { vcard:fn xsd:string {1} ; - - # This is intended to refer to the Individual's WebIDs, - # or other 'types', such as...? - vcard:url vcard:WebId {1}; - - # What is this intended to refer to? + + # vcard:WebId is a custom term + vcard:url vcard:WebId {1}; + + # Not sure if we use this anymore vcard:hasUID xsd:string ? ; - + vcard:hasName xsd:string ? ; # structured name vcard:hasPhoto dcterms:Image * ; vcard:hasRelated vcard:RelatedType * ; @@ -28,22 +34,16 @@ vcard:Individual { vcard:role xsd:string ? ; vcard:title xsd:string ? ; vcard:note xsd:string ? ; - - # These terms don't exist in vCard yet... vcard:inAddressBook vcard:AddressBook + ; + # vcard:inAddressBook is a custom term + # vcard:AddressBook is a custom class } -# This term doesn't exist in vCard yet... +# We store the preferred WebID for each person. The use of vcard:WebId +# refer to the Individual's WebIDs, but the idea is that we could expand it +# to refer to other type of unique identifiers later +# vcard:WebId is a custom term # Big question - SHOULD something as fundamental as WebID be defined in vCard? -# -# An example of usage (in Turtle) showing the relation with 'vcard:url' -# might be really useful here - for example, is this correct...? -# a vcard:Individual ; -# vcard:url . -# -# a vcard:WebID ; -# vcard:value "????"^^xsd:string . -# vcard:WebId { vcard:value xsd:string {1}; } From 29b802faf057767fcee5c2b56dfac9307e69a67b Mon Sep 17 00:00:00 2001 From: Arne Hassel Date: Fri, 5 Feb 2021 10:49:39 +0100 Subject: [PATCH 03/20] Update shapes/contacts/address-book.shex Co-authored-by: Pat McBennett --- shapes/contacts/address-book.shex | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/shapes/contacts/address-book.shex b/shapes/contacts/address-book.shex index 915b54d8..642f7b3a 100644 --- a/shapes/contacts/address-book.shex +++ b/shapes/contacts/address-book.shex @@ -3,8 +3,8 @@ PREFIX dc: PREFIX vcard: PREFIX xsd: -# This shape describes some of the information we store for an address book. The -# resource it is used for is to describe a single address book. We use the id +# This shape describes some of the information we store for an address book. It's +# intended to represent a single address book. We use the ID # "#this" to refer to the subject of the address book. # This model is originally developed as part of the From 31837cc32e0fbc84ee03d47db956d9eb0df417b9 Mon Sep 17 00:00:00 2001 From: Arne Hassel Date: Fri, 5 Feb 2021 10:52:35 +0100 Subject: [PATCH 04/20] Trying to make documentation text in bookmarks clearer --- shapes/bookmarks/bookmark.shex | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/shapes/bookmarks/bookmark.shex b/shapes/bookmarks/bookmark.shex index 3ff9a1ca..fb90eafd 100644 --- a/shapes/bookmarks/bookmark.shex +++ b/shapes/bookmarks/bookmark.shex @@ -3,8 +3,9 @@ PREFIX foaf: PREFIX terms: PREFIX xsd: -# This shape describes some the information we store a bookmark. The -# resource it is used describes multiple bookmarks. +# This shape describes the information we store for a bookmark. In PodBrowser +# we store all bookmarks in the same resource (i.e. we don't store one bookmark +# per resource, and then have another resource function as the index for them). bookmark:Bookmark { terms:created xsd:dateTime {1} ; From b1cc5f6256aca726f347b728ebddaaa1cb298387 Mon Sep 17 00:00:00 2001 From: Arne Hassel Date: Fri, 5 Feb 2021 10:56:38 +0100 Subject: [PATCH 05/20] Update shapes/contacts/group-index.shex Co-authored-by: Pat McBennett --- shapes/contacts/group-index.shex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/shapes/contacts/group-index.shex b/shapes/contacts/group-index.shex index fa15f6fe..7c23524a 100644 --- a/shapes/contacts/group-index.shex +++ b/shapes/contacts/group-index.shex @@ -6,7 +6,7 @@ PREFIX xsd: # be multiple groups added in this resource, and each referring to the group # resource where there are more information on the group (e.g. members). -# This model is originally developed as part of the +# This model was originally developed as part of the # SolidOS/Data Browser project, and we strive to keep it interoperable with # their work. Some custom terms have been introduced to vocabularies we think # they could belong to (e.g. vcard:includesGroup). We'll make a note of the From a11c58b2a3ef0e29e9b3b60d41fcd634c34e6dae Mon Sep 17 00:00:00 2001 From: Arne Hassel Date: Fri, 5 Feb 2021 10:56:45 +0100 Subject: [PATCH 06/20] Update shapes/contacts/address-book.shex Co-authored-by: Pat McBennett --- shapes/contacts/address-book.shex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/shapes/contacts/address-book.shex b/shapes/contacts/address-book.shex index 642f7b3a..8ce05562 100644 --- a/shapes/contacts/address-book.shex +++ b/shapes/contacts/address-book.shex @@ -7,7 +7,7 @@ PREFIX xsd: # intended to represent a single address book. We use the ID # "#this" to refer to the subject of the address book. -# This model is originally developed as part of the +# This model was originally developed as part of the # SolidOS/Data Browser project, and we strive to keep it interoperable with # their work. Some custom terms have been introduced to vocabularies we think # they could belong to (e.g. vcard:nameEmailIndex). We'll make a note of the From 0495328d44a22a3133937d2b540a8c1898711321 Mon Sep 17 00:00:00 2001 From: Arne Hassel Date: Fri, 5 Feb 2021 10:57:04 +0100 Subject: [PATCH 07/20] Update shapes/contacts/group.shex Co-authored-by: Pat McBennett --- shapes/contacts/group.shex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/shapes/contacts/group.shex b/shapes/contacts/group.shex index f6db9b18..6dfdcb4b 100644 --- a/shapes/contacts/group.shex +++ b/shapes/contacts/group.shex @@ -6,7 +6,7 @@ PREFIX xsd: # (meaning the resource should only contain one group). We use the id "#this" # to refer to the subject of the group. -# This model is originally developed as part of the +# This model was originally developed as part of the # SolidOS/Data Browser project, and we strive to keep it interoperable with # their work. Some custom terms have been introduced to vocabularies we think # they could belong to (e.g. vcard:includesGroup). We'll make a note of the From 681cc691b95f9b60a76f3ee9d04f2c4daf9b1e47 Mon Sep 17 00:00:00 2001 From: Arne Hassel Date: Fri, 5 Feb 2021 11:54:19 +0100 Subject: [PATCH 08/20] Added examples for address book and bookmarks --- shapes/bookmarks/example/index.ttl | 16 ++++++++++++++ shapes/contacts/example/Group/Group_1.ttl | 13 ++++++++++++ shapes/contacts/example/Group/Group_2.ttl | 10 +++++++++ .../index.ttl | 15 +++++++++++++ .../index.ttl | 11 ++++++++++ shapes/contacts/example/groups.ttl | 21 +++++++++++++++++++ shapes/contacts/example/index.ttl | 10 +++++++++ shapes/contacts/example/people.ttl | 10 +++++++++ 8 files changed, 106 insertions(+) create mode 100644 shapes/bookmarks/example/index.ttl create mode 100644 shapes/contacts/example/Group/Group_1.ttl create mode 100644 shapes/contacts/example/Group/Group_2.ttl create mode 100644 shapes/contacts/example/Person/2d73ccc1-9d76-4398-8840-3c23a8ddf04c/index.ttl create mode 100644 shapes/contacts/example/Person/347429c1-e6b5-40c0-bd6f-61ba1265d357/index.ttl create mode 100644 shapes/contacts/example/groups.ttl create mode 100644 shapes/contacts/example/index.ttl create mode 100644 shapes/contacts/example/people.ttl diff --git a/shapes/bookmarks/example/index.ttl b/shapes/bookmarks/example/index.ttl new file mode 100644 index 00000000..cbb6f6e3 --- /dev/null +++ b/shapes/bookmarks/example/index.ttl @@ -0,0 +1,16 @@ +@prefix : <#>. +@prefix bookm: . +@prefix terms: . +@prefix XML: . + +:16115748945888512870652861511 + a bookm:Bookmark; + terms:created "2021-01-25T11:41:34.589Z"^^XML:dateTime; + terms:title "Solid Project"; + bookm:recalls . + +:12391230834289702394820340982 + a bookm:Bookmark; + terms:created "2021-01-30T12:30:21.321Z"^^XML:dateTime; + terms:title "Inrupt"; + bookm:recalls . diff --git a/shapes/contacts/example/Group/Group_1.ttl b/shapes/contacts/example/Group/Group_1.ttl new file mode 100644 index 00000000..4e7237d4 --- /dev/null +++ b/shapes/contacts/example/Group/Group_1.ttl @@ -0,0 +1,13 @@ +@prefix : <#>. +@prefix vcard: . + +:this + a vcard:Group; + vcard:fn "Group 1"; + vcard:hasMember <../Person/67fca8b3-c74a-499e-b00f-67c543fa533f/index.ttl#this>. + +<../index.ttl#this> vcard:includesGroup :this. + +<../Person/67fca8b3-c74a-499e-b00f-67c543fa533f/index.ttl#this> + vcard:fn "Arne demo 1". + diff --git a/shapes/contacts/example/Group/Group_2.ttl b/shapes/contacts/example/Group/Group_2.ttl new file mode 100644 index 00000000..53840612 --- /dev/null +++ b/shapes/contacts/example/Group/Group_2.ttl @@ -0,0 +1,10 @@ +@prefix : <#>. +@prefix vcard: . + +:this + a vcard:Group; + vcard:fn "Group 2". + +<../index.ttl#this> + vcard:includesGroup :this. + diff --git a/shapes/contacts/example/Person/2d73ccc1-9d76-4398-8840-3c23a8ddf04c/index.ttl b/shapes/contacts/example/Person/2d73ccc1-9d76-4398-8840-3c23a8ddf04c/index.ttl new file mode 100644 index 00000000..a6c2f1a1 --- /dev/null +++ b/shapes/contacts/example/Person/2d73ccc1-9d76-4398-8840-3c23a8ddf04c/index.ttl @@ -0,0 +1,15 @@ +@prefix : <#>. +@prefix dcterms: . +@prefix XML: . +@prefix vcard: . + +<> + dcterms:created "2021-02-04T06:19:42Z"^^XML:dateTime. + +:this + a vcard:Individual; + vcard:fn "Arne H (demo1)"; + vcard:url [ + a vcard:WebID; + vcard:value "https://megoth-demo1.inrupt.net/profile/card#me" + ]. diff --git a/shapes/contacts/example/Person/347429c1-e6b5-40c0-bd6f-61ba1265d357/index.ttl b/shapes/contacts/example/Person/347429c1-e6b5-40c0-bd6f-61ba1265d357/index.ttl new file mode 100644 index 00000000..e3aac88c --- /dev/null +++ b/shapes/contacts/example/Person/347429c1-e6b5-40c0-bd6f-61ba1265d357/index.ttl @@ -0,0 +1,11 @@ +@prefix : <#>. +@prefix vcard: . + +:this + a vcard:Individual; + vcard:url :16112499761464744406237652592; + vcard:fn "Vincent". + +:16112499761464744406237652592 + a vcard:WebId; + vcard:value . diff --git a/shapes/contacts/example/groups.ttl b/shapes/contacts/example/groups.ttl new file mode 100644 index 00000000..2cf8323f --- /dev/null +++ b/shapes/contacts/example/groups.ttl @@ -0,0 +1,21 @@ +@prefix : <#>. +@prefix vcard: . + + + a vcard:Group; + vcard:fn "Group 1". + + + a vcard:Group; + vcard:fn "Group 2". + + + a vcard:Group; + vcard:fn "TEst". + + + vcard:includesGroup + , + , + . + diff --git a/shapes/contacts/example/index.ttl b/shapes/contacts/example/index.ttl new file mode 100644 index 00000000..ea4ceb6b --- /dev/null +++ b/shapes/contacts/example/index.ttl @@ -0,0 +1,10 @@ +@prefix : <#>. +@prefix acl: . +@prefix dcterms: . +@prefix vcard: . + +:this a vcard:AddressBook; + acl:owner ; + dcterms:title "Contacts"; + vcard:nameEmailIndex ; + vcard:groupIndex . diff --git a/shapes/contacts/example/people.ttl b/shapes/contacts/example/people.ttl new file mode 100644 index 00000000..001dedc6 --- /dev/null +++ b/shapes/contacts/example/people.ttl @@ -0,0 +1,10 @@ +@prefix : <#>. +@prefix vcard: . + + + vcard:fn "Arne H (demo1)"; + vcard:inAddressBook . + + + vcard:fn "Vincent"; + vcard:inAddressBook . From 6ab42a700b69f9a5500820cf19fde658695da391 Mon Sep 17 00:00:00 2001 From: Arne Hassel Date: Fri, 5 Feb 2021 12:11:54 +0100 Subject: [PATCH 09/20] Added comment about caching the name of each member in a group --- shapes/contacts/group.shex | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/shapes/contacts/group.shex b/shapes/contacts/group.shex index 6dfdcb4b..0c673918 100644 --- a/shapes/contacts/group.shex +++ b/shapes/contacts/group.shex @@ -20,3 +20,7 @@ vcard:Group { # vcard:AddressBook is a custom class ^vcard:includesGroup vcard:AddressBook } + +# Note that we also cache the name of each member, so that we don't have to +# fetch the profile of each member to get their name. An example of this can +# be seen in example/Group/Group_1.ttl. From 56fff0bec29451c3708684e7b98ed55922b2e264 Mon Sep 17 00:00:00 2001 From: pmcb55 Date: Mon, 8 Feb 2021 10:31:46 +0000 Subject: [PATCH 10/20] minor tweaks to Shapes README --- shapes/README.md | 113 +++++++++++++++++++++++++++-------------------- 1 file changed, 65 insertions(+), 48 deletions(-) diff --git a/shapes/README.md b/shapes/README.md index 5698f940..f09d1dc6 100644 --- a/shapes/README.md +++ b/shapes/README.md @@ -2,105 +2,122 @@ ## Bookmarks -We've decided to keep the structure of bookmarks simple, only storing `terms:created`, `terms:title`, and -`bookmark:recalls`. Note that some Solid bookmarking apps also use `foaf:maker`, but we didn't think it necessary in the +We've decided to keep the structure of bookmarks simple, only storing +`dcterms:created`, `dcterms:title`, and `bookmark:recalls`. Note that some Solid +bookmarking apps also use `foaf:maker`, but we didn't think it necessary in the context of the PodBrowser, so we've chosen to make it optional. -We've also decided to omit the use of an index using `dct:references`, as this would require us to keep the index -up-to-date manually, and we think it's better to find the bookmarks using the `bookmark:Bookmark` class. +We've also decided to omit the use of an index using `dcterms:references`, as +this would require us to keep the index up-to-date manually, and we think it's +better to find the bookmarks using the `bookmark:Bookmark` class. -At some point we might need to group bookmarks, but at this point we've chosen to keep it simple and simply -implement bookmarks as a set of bookmarks that are stored in one file. +At some point we might need to group bookmarks, but at this point we've chosen +to keep it simple and simply implement bookmarks as a set of bookmarks that are +stored in one file. ## Contacts -Because there are some differences between the ShEx shapes we've described and previous work on SHACL shapes we wanted -to explain the differences those shapes. Once they have been resolved, we might remove this README altogether. +Because there are some differences between the ShEx shapes we've described and +previous work on SHACL shapes we wanted to explain the differences those shapes. +Once they have been resolved, we might remove this README altogether. ### Address Book: Differences between ShEx and SHACL -The following is how the SHACL shape in `https://raw.githubusercontent.com/solid/contacts-pane/master/shapes/contacts-shapes.ttl` differs from the ShEx shape in `contacts/address-book.shex`. +The following is how the SHACL shape in +`https://raw.githubusercontent.com/solid/contacts-pane/master/shapes/contacts-shapes.ttl` +differs from the ShEx shape in `contacts/address-book.shex`. - vcard:AddressBook - vcard:fn (instead of dc:title) - - There can be one or more instances + - There can be one or more instances. - vcard:nameEmailIndex - - There can be one or more instances - - There is not a specific datatype set + - There can be one or more instances. + - There is not a specific datatype set. - vcard:vcard:groupIndex - - Using terms (sh:count, sh:FollowMe) that isn't formalized + - Using terms (sh:count, sh:FollowMe) that isn't formalized. ### Group Index: Differences between ShEx and SHACL -The following is how the SHACL shape in `https://raw.githubusercontent.com/solid/contacts-pane/master/shapes/contacts-shapes.ttl` differ from the ShEx shape in `contacts/group-index.shex`. +The following is how the SHACL shape in +`https://raw.githubusercontent.com/solid/contacts-pane/master/shapes/contacts-shapes.ttl` +differ from the ShEx shape in `contacts/group-index.shex`. - vcard:AddressBook - vcard:fn - - Different cardinality ({1,m} vs {1,1}) + - Different cardinality ({1,m} vs {1,1}). - vcard:includesGroup - - We used an inverse triple constraint instead (putting this term under vcard:Group shape instead) + - We used an inverse triple constraint instead (putting this term under + vcard:Group shape instead). ### Group: Differences between ShEx and SHACL -The following is how the SHACL shape in `https://raw.githubusercontent.com/solid/contacts-pane/master/shapes/contacts-shapes.ttl` differ from the ShEx shape in `contacts/group.shex`. +The following is how the SHACL shape in +`https://raw.githubusercontent.com/solid/contacts-pane/master/shapes/contacts-shapes.ttl` +differ from the ShEx shape in `contacts/group.shex`. - vcard:AddressBook - vcard:includesGroup - - Using informal terms (sh:count, sh:FollowMe) + - Using informal terms (sh:count, sh:FollowMe). - vcard:Group - - vcard:fn cardinality difference (one or more instead of just one) - - vcard:member (informal term) instead of vcard:hasMember + - vcard:fn cardinality difference (one or more instead of just one). + - vcard:member (informal term) instead of vcard:hasMember. ### People Index: Differences between ShEx and SHACL -The following is how the SHACL shape in `https://raw.githubusercontent.com/solid/contacts-pane/master/shapes/contacts-shapes.ttl` differ from the ShEx shape in `contacts/people-index.shex`. +The following is how the SHACL shape in +`https://raw.githubusercontent.com/solid/contacts-pane/master/shapes/contacts-shapes.ttl` +differ from the ShEx shape in `contacts/people-index.shex`. - vcard:Individual - vcard:inAddressBook - - uses informal term sh:BackwardLink - - minimum and maximum one instance of IRI (can be part of only one address book) + - uses informal term sh:BackwardLink. + - minimum and maximum one instance of IRI (can be part of only one address + book). ### Person: Differences between ShEx and SHACL -The following is how the SHACL shape in `https://raw.githubusercontent.com/solid/contacts-pane/master/shapes/contacts-shapes.ttl` differ from the ShEx shape in `contacts/person.shex`. +The following is how the SHACL shape in +`https://raw.githubusercontent.com/solid/contacts-pane/master/shapes/contacts-shapes.ttl` +differ from the ShEx shape in `contacts/person.shex`. - vcard:Individual - - is closed - - using informal term sh:count + - is closed. + - using informal term sh:count. - vcard:fn - - uses sh:pattern ".* .*" + - uses sh:pattern ".* .*". - vcard:hasUID - - different cardinality ({1, 1} vs {0, 1}) - - uses sh:pattern "^urn:uuid:" + - different cardinality ({1, 1} vs {0, 1}). + - uses sh:pattern "^urn:uuid:". - vcard:hasName - - has a shape of its own (:NameShape) + - has a shape of its own (:NameShape): - vcard:family-name - vcard:given-name - vcard:additional-name - vcard:honorific-prefix - vcard:honorific-suffix - - we used string, but added a comment + - we used string, but added a comment. - vcard:hasImage - - don't specify type dc:Image + - don't specify type dc:Image. - vcard:hasRelated - - don't specify node or sub-shape (we specified a shape for vcard:RelatedType in ShEx) + - don't specify node or sub-shape (we specified a shape for + vcard:RelatedType in ShEx). - vcard:url - - has a shape of its own (:WebPageShape) - - uses vcard:value (vs rdf:value) - - uses sh:pattern "^https?:" - - uses informal term sh:count - - we specified type rdf:Resource in the ShEx shape + - has a shape of its own (:WebPageShape): + - uses vcard:value (vs rdf:value). + - uses sh:pattern "^https?:". + - uses informal term sh:count. + - we specified type rdf:Resource in the ShEx shape. - vcard:hasAddress - - don't specify node or sub-shape (vcard:Address) + - don't specify node or sub-shape (vcard:Address). - vcard:anniversary - - we used vcard:bday in the ShEx shape + - we used vcard:bday in the ShEx shape. - vcard:hasEmail - - uses sh:pattern "^mailto:" (vs /^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$/ in ShEx) - - uses vcard:value (vs rdf:value) - - uses informal term sh:count - - different cardinality (ShEx is *) + - uses sh:pattern "^mailto:" (vs /^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$/ in ShEx). + - uses vcard:value (vs rdf:value). + - uses informal term sh:count. + - different cardinality (ShEx is *). - vcard:hasTelephone - - uses sh:pattern "^tel:" (vs /^\+?[0-9]+[0-9-]*[0-9]$/ in ShEx) - - uses vcard:value (vs rdf:value) - - uses informal term sh:count - - different cardinality (ShEx is *) + - uses sh:pattern "^tel:" (vs /^\+?[0-9]+[0-9-]*[0-9]$/ in ShEx). + - uses vcard:value (vs rdf:value). + - uses informal term sh:count. + - different cardinality (ShEx is *). From 6c4d577684b01265ec4e377ab557df2cbde43c7a Mon Sep 17 00:00:00 2001 From: pmcb55 Date: Mon, 8 Feb 2021 11:21:54 +0000 Subject: [PATCH 11/20] more very minor English tweaks --- shapes/README.md | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/shapes/README.md b/shapes/README.md index f09d1dc6..cb6399ae 100644 --- a/shapes/README.md +++ b/shapes/README.md @@ -18,8 +18,9 @@ stored in one file. ## Contacts Because there are some differences between the ShEx shapes we've described and -previous work on SHACL shapes we wanted to explain the differences those shapes. -Once they have been resolved, we might remove this README altogether. +previous work on SHACL shapes we wanted to explain the differences between those +shapes. Once these differences have been resolved, we might remove this README +altogether. ### Address Book: Differences between ShEx and SHACL @@ -32,15 +33,15 @@ differs from the ShEx shape in `contacts/address-book.shex`. - There can be one or more instances. - vcard:nameEmailIndex - There can be one or more instances. - - There is not a specific datatype set. - - vcard:vcard:groupIndex - - Using terms (sh:count, sh:FollowMe) that isn't formalized. + - There is no specific datatype set. + - vcard:groupIndex + - Uses terms (e.g., sh:count, sh:FollowMe) that aren't formalized. ### Group Index: Differences between ShEx and SHACL The following is how the SHACL shape in `https://raw.githubusercontent.com/solid/contacts-pane/master/shapes/contacts-shapes.ttl` -differ from the ShEx shape in `contacts/group-index.shex`. +differs from the ShEx shape in `contacts/group-index.shex`. - vcard:AddressBook - vcard:fn @@ -53,7 +54,7 @@ differ from the ShEx shape in `contacts/group-index.shex`. The following is how the SHACL shape in `https://raw.githubusercontent.com/solid/contacts-pane/master/shapes/contacts-shapes.ttl` -differ from the ShEx shape in `contacts/group.shex`. +differs from the ShEx shape in `contacts/group.shex`. - vcard:AddressBook - vcard:includesGroup @@ -66,19 +67,19 @@ differ from the ShEx shape in `contacts/group.shex`. The following is how the SHACL shape in `https://raw.githubusercontent.com/solid/contacts-pane/master/shapes/contacts-shapes.ttl` -differ from the ShEx shape in `contacts/people-index.shex`. +differs from the ShEx shape in `contacts/people-index.shex`. - vcard:Individual - vcard:inAddressBook - uses informal term sh:BackwardLink. - - minimum and maximum one instance of IRI (can be part of only one address - book). + - minimum and maximum one instance of IRI (i.e., can only be referenced from + one address book). ### Person: Differences between ShEx and SHACL The following is how the SHACL shape in `https://raw.githubusercontent.com/solid/contacts-pane/master/shapes/contacts-shapes.ttl` -differ from the ShEx shape in `contacts/person.shex`. +differs from the ShEx shape in `contacts/person.shex`. - vcard:Individual - is closed. From 065237cb5b04a47ad84867406afeddeae47c9841 Mon Sep 17 00:00:00 2001 From: pmcb55 Date: Tue, 9 Feb 2021 12:54:54 +0000 Subject: [PATCH 12/20] create my example structure - example2 --- shapes/README.md | 37 +++++++++++++-- shapes/contacts/address-book.shex | 6 +-- shapes/contacts/example/groups.ttl | 7 +-- shapes/contacts/example2/README.md | 47 +++++++++++++++++++ .../example2/addressBookFriend/index.ttl | 16 +++++++ .../example2/addressBookWork/index.ttl | 16 +++++++ .../example2/group/group1-work-colleague.ttl | 20 ++++++++ .../contacts/example2/group/group2-friend.ttl | 20 ++++++++ .../example2/group/group3-soccer-team.ttl | 20 ++++++++ .../contacts/example2/group/group4-empty.ttl | 11 +++++ shapes/contacts/example2/group/index.ttl | 36 ++++++++++++++ .../index.ttl | 25 ++++++++++ .../index.ttl | 17 +++++++ .../index.ttl | 17 +++++++ shapes/contacts/example2/person/index.ttl | 23 +++++++++ .../{people-index.shex => person-index.shex} | 0 16 files changed, 305 insertions(+), 13 deletions(-) create mode 100644 shapes/contacts/example2/README.md create mode 100644 shapes/contacts/example2/addressBookFriend/index.ttl create mode 100644 shapes/contacts/example2/addressBookWork/index.ttl create mode 100644 shapes/contacts/example2/group/group1-work-colleague.ttl create mode 100644 shapes/contacts/example2/group/group2-friend.ttl create mode 100644 shapes/contacts/example2/group/group3-soccer-team.ttl create mode 100644 shapes/contacts/example2/group/group4-empty.ttl create mode 100644 shapes/contacts/example2/group/index.ttl create mode 100644 shapes/contacts/example2/person/2d73ccc1-9d76-4398-8840-3c23a8ddf04c/index.ttl create mode 100644 shapes/contacts/example2/person/347429c1-e6b5-40c0-bd6f-61ba1265d357/index.ttl create mode 100644 shapes/contacts/example2/person/76344edd-b1c7-67c2-ec3e-89ab5494e233/index.ttl create mode 100644 shapes/contacts/example2/person/index.ttl rename shapes/contacts/{people-index.shex => person-index.shex} (100%) diff --git a/shapes/README.md b/shapes/README.md index cb6399ae..61ad83b5 100644 --- a/shapes/README.md +++ b/shapes/README.md @@ -1,5 +1,34 @@ # Shapes +## Indexes + +We use the term 'index' throughout our modelling to refer to a single RDF +resource that acts as a container for multiple 'contained' instances, where each +contained instance may refer to an external resource, and may also contain +copies of (some of the) data from that external resource +**** +(e.g., an instance may copy fields from an external resource, plus have a link +to that external resouce). +**** + + +We choose not to model these collections using either native RDF lists (e.g., +`rdf:Seq`), nor LDP containers, nor some existing list or set vocabulary (e.g., +such as Schema.org's [ItemList](https://schema.org/ItemList), or the Ordered +List Ontology ([OLO](http://smiy.sourceforge.net/olo/spec/orderedlistontology.html))). +The reasons for this were: + - Originally modelled around limitations of the first Solid server (NSS). + - Allows highly efficiency retrieval of contained resource data by having it + all in the index resource, and not make resource-by-resource requests. + +#### Example of index use + +For example, a single AddressBook resource may reference two indexes, one for +the collection of emails addresses in that AddressBook (i.e., using the +predicate `vcard:nameEmailIndex`), and one for the collection of groups in that +AddressBook (i.e., using the predicate `vcard:groupIndex`). +Each index resource + ## Bookmarks We've decided to keep the structure of bookmarks simple, only storing @@ -18,9 +47,9 @@ stored in one file. ## Contacts Because there are some differences between the ShEx shapes we've described and -previous work on SHACL shapes we wanted to explain the differences between those -shapes. Once these differences have been resolved, we might remove this README -altogether. +previous work on SHACL shapes, we wanted to explain the differences between +those shapes. Once these differences have all been resolved, we might remove +this README altogether. ### Address Book: Differences between ShEx and SHACL @@ -67,7 +96,7 @@ differs from the ShEx shape in `contacts/group.shex`. The following is how the SHACL shape in `https://raw.githubusercontent.com/solid/contacts-pane/master/shapes/contacts-shapes.ttl` -differs from the ShEx shape in `contacts/people-index.shex`. +differs from the ShEx shape in `contacts/person-index.shex`. - vcard:Individual - vcard:inAddressBook diff --git a/shapes/contacts/address-book.shex b/shapes/contacts/address-book.shex index 8ce05562..a69d695b 100644 --- a/shapes/contacts/address-book.shex +++ b/shapes/contacts/address-book.shex @@ -3,9 +3,9 @@ PREFIX dc: PREFIX vcard: PREFIX xsd: -# This shape describes some of the information we store for an address book. It's -# intended to represent a single address book. We use the ID -# "#this" to refer to the subject of the address book. +# This shape describes some of the information we store for an address book. +# It's intended to represent a single address book. We use the ID "#this" to +# refer to the subject of the address book. # This model was originally developed as part of the # SolidOS/Data Browser project, and we strive to keep it interoperable with diff --git a/shapes/contacts/example/groups.ttl b/shapes/contacts/example/groups.ttl index 2cf8323f..e8f573ed 100644 --- a/shapes/contacts/example/groups.ttl +++ b/shapes/contacts/example/groups.ttl @@ -9,13 +9,8 @@ a vcard:Group; vcard:fn "Group 2". - - a vcard:Group; - vcard:fn "TEst". - vcard:includesGroup , - , - . + . diff --git a/shapes/contacts/example2/README.md b/shapes/contacts/example2/README.md new file mode 100644 index 00000000..328fa094 --- /dev/null +++ b/shapes/contacts/example2/README.md @@ -0,0 +1,47 @@ +# Example Turtle files + +The example Turtle files here describe the structure and modelling of the +following: + +### Two address books + +Modelled as **_containers_**: + +- Work colleagues (the `/addressBookWork` container). +- Friends (the `/addressBookFriend` container). + +### Four groups + +Modelled as individual **_resources_** within the `/group` container, and with +that `/group` container having an `index.ttl` Group-Index. + +- Work colleagues (`/group/group1-work-colleague.ttl`). +- Friends (`/group/group2-friend.ttl`). +- Local soccer team (`/group/group3-soccer-team.ttl`). +- Just an empty group (`/group/group4-empty.ttl`). + +And the Group-Index - `/group/index.ttl`. + +### Three people + +Each person modelled as a **_child container_** within the `/person` container, +with the parent `/person` container containing an `index.ttl` Person-Index. + +- Arne H, who I work with, is a friend I play D&G, and is the striker on my + local soccer team! +- Vincent T, who I work with. +- Tommy Mc, who is a friend. + +And the Person-Index - `/person/index.ttl`. + + +# Notes: + +- The use of `index.ttl` is a convention, but it seems to be used for both + 'indexes' (i.e., a Group index (e.g., `/group/index.ttl`) listing a number of + contained groups), and the 'default resource' of a container (e.g., the + `index.ttl` resource within the individual person container (e.g., + `/person/347429c1-e6b5-40c0-bd6f-61ba1265d357/index.ttl`). + +- In Group-Indexes, is it necessary to duplicate the triple stating that each + contained group is of `rdf:type` `vcard:Group`? diff --git a/shapes/contacts/example2/addressBookFriend/index.ttl b/shapes/contacts/example2/addressBookFriend/index.ttl new file mode 100644 index 00000000..ce90cdc9 --- /dev/null +++ b/shapes/contacts/example2/addressBookFriend/index.ttl @@ -0,0 +1,16 @@ +prefix : <#> +prefix acl: +prefix dcterms: +prefix vcard: + +# +# This is my address book that I use to list just my friends... +# It contains references to two indexes: +# - one listing my friends +# - one listing my groups of friends +# +:this a vcard:AddressBook ; + acl:owner ; + dcterms:title "Contacts of all my friends" ; + vcard:nameEmailIndex <../person/index.ttl> ; + vcard:groupIndex <../group/index.ttl> . diff --git a/shapes/contacts/example2/addressBookWork/index.ttl b/shapes/contacts/example2/addressBookWork/index.ttl new file mode 100644 index 00000000..5c998200 --- /dev/null +++ b/shapes/contacts/example2/addressBookWork/index.ttl @@ -0,0 +1,16 @@ +prefix : <#> +prefix acl: +prefix dcterms: +prefix vcard: + +# +# This is my address book that I use to list just my work colleagues... +# It contains references to two indexes: +# - one listing my work colleagues +# - one listing my groups of work colleagues +# +:this a vcard:AddressBook ; + acl:owner ; + dcterms:title "Contacts of all my work colleagues" ; + vcard:nameEmailIndex ; + vcard:groupIndex . diff --git a/shapes/contacts/example2/group/group1-work-colleague.ttl b/shapes/contacts/example2/group/group1-work-colleague.ttl new file mode 100644 index 00000000..b918a603 --- /dev/null +++ b/shapes/contacts/example2/group/group1-work-colleague.ttl @@ -0,0 +1,20 @@ +prefix : <#> +prefix vcard: + +:this + a vcard:Group ; + vcard:fn "Group 1" ; + vcard:hasMember <../Person/2d73ccc1-9d76-4398-8840-3c23a8ddf04c/index.ttl#this> ; + vcard:hasMember <../Person/347429c1-e6b5-40c0-bd6f-61ba1265d357/index.ttl#this> . + +<../addressBookFriend/index.ttl#this> vcard:includesGroup :this . + +# This is caching some data from an external resource by copying it here (just +# so that we don't need to fetch each `vcard:hasMember` instance to get their +# vcard:fn values. +<../person/2d73ccc1-9d76-4398-8840-3c23a8ddf04c/index.ttl#this> + vcard:fn "Arne - who I work with" . + +<../person/347429c1-e6b5-40c0-bd6f-61ba1265d357/index.ttl#this> + vcard:fn "Vincent - but name could be different here (since it's a copy)" . + diff --git a/shapes/contacts/example2/group/group2-friend.ttl b/shapes/contacts/example2/group/group2-friend.ttl new file mode 100644 index 00000000..f8fee1f8 --- /dev/null +++ b/shapes/contacts/example2/group/group2-friend.ttl @@ -0,0 +1,20 @@ +prefix : <#> +prefix vcard: + +:this + a vcard:Group ; + vcard:fn "Group 1" ; + vcard:hasMember <../Person/2d73ccc1-9d76-4398-8840-3c23a8ddf04c/index.ttl#this> ; + vcard:hasMember <../Person/347429c1-e6b5-40c0-bd6f-61ba1265d357/index.ttl#this> . + +<../addressBookFriend/index.ttl#this> vcard:includesGroup :this . + +# This is caching some data from an external resource by copying it here (just +# so that we don't need to fetch each `vcard:hasMember` instance to get their +# vcard:fn values. +<../person/2d73ccc1-9d76-4398-8840-3c23a8ddf04c/index.ttl#this> + vcard:fn "Arne - from work, but my mate from D&G" . + +<../person/76344edd-b1c7-67c2-ec3e-89ab5494e233/index.ttl#this> + vcard:fn "Tommy - friend from the soccer team" . + diff --git a/shapes/contacts/example2/group/group3-soccer-team.ttl b/shapes/contacts/example2/group/group3-soccer-team.ttl new file mode 100644 index 00000000..f30b7ddf --- /dev/null +++ b/shapes/contacts/example2/group/group3-soccer-team.ttl @@ -0,0 +1,20 @@ +prefix : <#> +prefix vcard: + +:this + a vcard:Group ; + vcard:fn "Group 1" ; + vcard:hasMember <../Person/2d73ccc1-9d76-4398-8840-3c23a8ddf04c/index.ttl#this> ; + vcard:hasMember <../Person/347429c1-e6b5-40c0-bd6f-61ba1265d357/index.ttl#this> . + +<../addressBookFriend/index.ttl#this> vcard:includesGroup :this . + +# This is caching some data from an external resource by copying it here (just +# so that we don't need to fetch each `vcard:hasMember` instance to get their +# vcard:fn values. +<../person/2d73ccc1-9d76-4398-8840-3c23a8ddf04c/index.ttl#this> + vcard:fn "Arne - soccer team striker!" . + +<../person/76344edd-b1c7-67c2-ec3e-89ab5494e233/index.ttl#this> + vcard:fn "Tommy - soccer team goalkeeper" . + diff --git a/shapes/contacts/example2/group/group4-empty.ttl b/shapes/contacts/example2/group/group4-empty.ttl new file mode 100644 index 00000000..ecb1e57e --- /dev/null +++ b/shapes/contacts/example2/group/group4-empty.ttl @@ -0,0 +1,11 @@ +prefix : <#> +prefix vcard: + +# This is simply an empty group (i.e., no members). +:this + a vcard:Group ; + vcard:fn "Group 2" . + +<../addressBookFriend/index.ttl#this> + vcard:includesGroup :this . + diff --git a/shapes/contacts/example2/group/index.ttl b/shapes/contacts/example2/group/index.ttl new file mode 100644 index 00000000..0cc0d361 --- /dev/null +++ b/shapes/contacts/example2/group/index.ttl @@ -0,0 +1,36 @@ +prefix : <#> +prefix vcard: + +# +# This is a Group-specific index. +# +# Here we cache (copy) some data from our 'contained' groups, in this case just +# the formatted name of each group (and since they are 'copies', they can have +# different values), and the fact that each is of `rdf:type` `vcard:Group`. +# +<./group1-work-colleague.ttl#this> + a vcard:Group ; + vcard:fn "Group 1 - all my work colleagues" . + +<./group2-friend.ttl#this> + a vcard:Group ; + vcard:fn "Group 2 - all my friends" . + +<./group3-soccer-team.ttl#this> + a vcard:Group ; + vcard:fn "Group 3 - my local soccer team" . + +<./group4-empty.ttl#this> + a vcard:Group ; + vcard:fn "Group 4 - which I expect to be empty" . + + +<../addressBookWork/index.ttl#this> + vcard:includesGroup + <./group1-work-colleague.ttl#this> . + +<../addressBookFriend/index.ttl#this> + vcard:includesGroup + <./group2-friend.ttl#this> , + <./group3-soccer-team.ttl#this> , + <./group4-empty.ttl#this> . diff --git a/shapes/contacts/example2/person/2d73ccc1-9d76-4398-8840-3c23a8ddf04c/index.ttl b/shapes/contacts/example2/person/2d73ccc1-9d76-4398-8840-3c23a8ddf04c/index.ttl new file mode 100644 index 00000000..52ef805e --- /dev/null +++ b/shapes/contacts/example2/person/2d73ccc1-9d76-4398-8840-3c23a8ddf04c/index.ttl @@ -0,0 +1,25 @@ +prefix : <#> +prefix dcterms: +prefix XML: +prefix vcard: + +# This data was generated when this 'Person' container was created initially +# via Data Browser and rdflib.js. +<> + dcterms:created "2021-02-04T06:19:42Z"^^XML:dateTime . + +# +# Here we describe the actual entity - in this case a Person. +# +:this + a vcard:Individual ; + vcard:fn "Arne H - work colleague, friend and soccer striker" ; + vcard:url [ + a vcard:WebID; + vcard:value "https://megoth-demo1.inrupt.net/profile/card#me" + ] , + # Perhaps other forms of dereferencable URL's (but not email!)... + [ + a vcard:DID; + vcard:value "did:sovrin:34537453453-2432424-23424324" + ] . diff --git a/shapes/contacts/example2/person/347429c1-e6b5-40c0-bd6f-61ba1265d357/index.ttl b/shapes/contacts/example2/person/347429c1-e6b5-40c0-bd6f-61ba1265d357/index.ttl new file mode 100644 index 00000000..30462aa0 --- /dev/null +++ b/shapes/contacts/example2/person/347429c1-e6b5-40c0-bd6f-61ba1265d357/index.ttl @@ -0,0 +1,17 @@ +prefix : <#> +prefix vcard: + +# +# Person instance saved via Pod Browser... +# +:this + a vcard:Individual ; + vcard:fn "Vincent T - work colleague" ; + vcard:url :16112499761464744406237652592 . + +# +# Using a named node (as opposed to a Blank Node). +# +:16112499761464744406237652592 + a vcard:WebId ; + vcard:value . diff --git a/shapes/contacts/example2/person/76344edd-b1c7-67c2-ec3e-89ab5494e233/index.ttl b/shapes/contacts/example2/person/76344edd-b1c7-67c2-ec3e-89ab5494e233/index.ttl new file mode 100644 index 00000000..f3d0919a --- /dev/null +++ b/shapes/contacts/example2/person/76344edd-b1c7-67c2-ec3e-89ab5494e233/index.ttl @@ -0,0 +1,17 @@ +prefix : <#> +prefix vcard: + +# +# Person instance saved via Pod Browser... +# +:this + a vcard:Individual ; + vcard:fn "Tommy - friend and goalkeeper extraordinaire" ; + vcard:url :56456268332379795455777077312 . + +# +# Using a named node (as opposed to a Blank Node). +# +:56456268332379795455777077312 + a vcard:WebId ; + vcard:value . diff --git a/shapes/contacts/example2/person/index.ttl b/shapes/contacts/example2/person/index.ttl new file mode 100644 index 00000000..873edf50 --- /dev/null +++ b/shapes/contacts/example2/person/index.ttl @@ -0,0 +1,23 @@ +prefix : <#> +prefix vcard: + +# +# This is a Person-specific index. +# +# We define a container for each Person (but for Groups we don't), and we +# can cache (or copy) specific data from each person to here in this index too +# (so that we can access that data without having to read all the individual +# people resources when just listing all the people with their names). + + vcard:fn "Arne H" ; + vcard:inAddressBook + <../addressBookFriend/index.ttl#this> , + <../addressBookWork/index.ttl#this> . + + + vcard:fn "Vincent" ; + vcard:inAddressBook <../addressBookWork/index.ttl#this> . + + + vcard:fn "Tommy Mc" ; + vcard:inAddressBook <../addressBookFriend/index.ttl#this> . diff --git a/shapes/contacts/people-index.shex b/shapes/contacts/person-index.shex similarity index 100% rename from shapes/contacts/people-index.shex rename to shapes/contacts/person-index.shex From 24f290c85b51da79af7c868638187df1ac6d42c7 Mon Sep 17 00:00:00 2001 From: pmcb55 Date: Tue, 9 Feb 2021 17:27:38 +0000 Subject: [PATCH 13/20] cleaned up to just one Shape example directory --- shapes/README.md | 45 +++++++++++++------ shapes/bookmarks/README.md | 5 +++ shapes/bookmarks/bookmark.shex | 10 +++-- .../example/{ => bookmark}/index.ttl | 0 shapes/contacts/example/Group/Group_1.ttl | 13 ------ shapes/contacts/example/Group/Group_2.ttl | 10 ----- .../index.ttl | 15 ------- .../index.ttl | 11 ----- .../contacts/{example2 => example}/README.md | 4 +- .../addressBookFriend/index.ttl | 0 .../addressBookWork/index.ttl | 0 .../group/group1-work-colleague.ttl | 0 .../group/group2-friend.ttl | 0 .../group/group3-soccer-team.ttl | 0 .../group/group4-empty.ttl | 0 .../{example2 => example}/group/index.ttl | 0 shapes/contacts/example/groups.ttl | 16 ------- shapes/contacts/example/index.ttl | 10 ----- shapes/contacts/example/people.ttl | 10 ----- .../index.ttl | 0 .../index.ttl | 0 .../index.ttl | 0 .../{example2 => example}/person/index.ttl | 0 23 files changed, 44 insertions(+), 105 deletions(-) create mode 100644 shapes/bookmarks/README.md rename shapes/bookmarks/example/{ => bookmark}/index.ttl (100%) delete mode 100644 shapes/contacts/example/Group/Group_1.ttl delete mode 100644 shapes/contacts/example/Group/Group_2.ttl delete mode 100644 shapes/contacts/example/Person/2d73ccc1-9d76-4398-8840-3c23a8ddf04c/index.ttl delete mode 100644 shapes/contacts/example/Person/347429c1-e6b5-40c0-bd6f-61ba1265d357/index.ttl rename shapes/contacts/{example2 => example}/README.md (95%) rename shapes/contacts/{example2 => example}/addressBookFriend/index.ttl (100%) rename shapes/contacts/{example2 => example}/addressBookWork/index.ttl (100%) rename shapes/contacts/{example2 => example}/group/group1-work-colleague.ttl (100%) rename shapes/contacts/{example2 => example}/group/group2-friend.ttl (100%) rename shapes/contacts/{example2 => example}/group/group3-soccer-team.ttl (100%) rename shapes/contacts/{example2 => example}/group/group4-empty.ttl (100%) rename shapes/contacts/{example2 => example}/group/index.ttl (100%) delete mode 100644 shapes/contacts/example/groups.ttl delete mode 100644 shapes/contacts/example/index.ttl delete mode 100644 shapes/contacts/example/people.ttl rename shapes/contacts/{example2 => example}/person/2d73ccc1-9d76-4398-8840-3c23a8ddf04c/index.ttl (100%) rename shapes/contacts/{example2 => example}/person/347429c1-e6b5-40c0-bd6f-61ba1265d357/index.ttl (100%) rename shapes/contacts/{example2 => example}/person/76344edd-b1c7-67c2-ec3e-89ab5494e233/index.ttl (100%) rename shapes/contacts/{example2 => example}/person/index.ttl (100%) diff --git a/shapes/README.md b/shapes/README.md index 61ad83b5..b7a3b69f 100644 --- a/shapes/README.md +++ b/shapes/README.md @@ -1,33 +1,50 @@ # Shapes +## Structure of the Shapes contained here. + +This directory contains the following sub-directories, each containing ShEx +Shapes and an `/example` folder showing demonstration Turtle files conforming +to the relevant Shapes. The Turtle files are also used to demonstrate how +instances of Pod Resources are expected to be interlinked + ## Indexes -We use the term 'index' throughout our modelling to refer to a single RDF -resource that acts as a container for multiple 'contained' instances, where each -contained instance may refer to an external resource, and may also contain -copies of (some of the) data from that external resource -**** -(e.g., an instance may copy fields from an external resource, plus have a link -to that external resouce). -**** +We use the term 'index' throughout our modelling with two very different +interpretations: + + - Index in the sense of a single Pod resource containing a collection of + entities. E.g., a single Person-Index resource might contain a list of 50 + Person instances, where each instance contains a reference (or link) to the + actual Person resource elsewhere in my Pod, but may also contain a copy of + the Person's name and profile image perhaps, directly in the index too. + - Index in the sense of a '_default resource to look for when navigating to a + Container_'. In much the same way as browsers will automatically look for a + resource named 'index.html' when browsing to a website, our modelling can + store resources named 'index.ttl' in the root of containers, which our + applications can then expect to contain app-specific information. +### Indexes as 'efficient containers for a collection of entities' -We choose not to model these collections using either native RDF lists (e.g., +We chose not to model these collections using either native RDF lists (e.g., `rdf:Seq`), nor LDP containers, nor some existing list or set vocabulary (e.g., such as Schema.org's [ItemList](https://schema.org/ItemList), or the Ordered List Ontology ([OLO](http://smiy.sourceforge.net/olo/spec/orderedlistontology.html))). The reasons for this were: - - Originally modelled around limitations of the first Solid server (NSS). - - Allows highly efficiency retrieval of contained resource data by having it - all in the index resource, and not make resource-by-resource requests. + - This was originally modelled around limitations of the first Solid server + (NSS). + - Efficiency reasons, i.e., where we wish to retrieve a collection of entities + in a single HTTP resource request (e.g., a list of people, perhaps with just + their first name and date-of-birth values), as opposed to needing to make + multiple HTTP requests, one for each Person resource in our list. + #### Example of index use For example, a single AddressBook resource may reference two indexes, one for -the collection of emails addresses in that AddressBook (i.e., using the +the collection of email addresses in that AddressBook (i.e., using the predicate `vcard:nameEmailIndex`), and one for the collection of groups in that AddressBook (i.e., using the predicate `vcard:groupIndex`). -Each index resource + ## Bookmarks diff --git a/shapes/bookmarks/README.md b/shapes/bookmarks/README.md new file mode 100644 index 00000000..6aa71a13 --- /dev/null +++ b/shapes/bookmarks/README.md @@ -0,0 +1,5 @@ +# Bookmark-related Turtle files + +Bookmarks are modelled very simply. Due to this simplicity at the moment, we've +choosen to model a collection of bookmarks as simply being entities contained +within a single resource (as opposed to defining a resource-per-bookmark). \ No newline at end of file diff --git a/shapes/bookmarks/bookmark.shex b/shapes/bookmarks/bookmark.shex index fb90eafd..59712860 100644 --- a/shapes/bookmarks/bookmark.shex +++ b/shapes/bookmarks/bookmark.shex @@ -3,10 +3,12 @@ PREFIX foaf: PREFIX terms: PREFIX xsd: -# This shape describes the information we store for a bookmark. In PodBrowser -# we store all bookmarks in the same resource (i.e. we don't store one bookmark -# per resource, and then have another resource function as the index for them). - +# +# This shape describes the information we store for a bookmark. +# In Pod Browser we store all bookmarks within the one resource (as opposed to +# storing one bookmark per resource and containing them all within an +# `ldp:Container`). +# bookmark:Bookmark { terms:created xsd:dateTime {1} ; terms:title xsd:string {1} ; diff --git a/shapes/bookmarks/example/index.ttl b/shapes/bookmarks/example/bookmark/index.ttl similarity index 100% rename from shapes/bookmarks/example/index.ttl rename to shapes/bookmarks/example/bookmark/index.ttl diff --git a/shapes/contacts/example/Group/Group_1.ttl b/shapes/contacts/example/Group/Group_1.ttl deleted file mode 100644 index 4e7237d4..00000000 --- a/shapes/contacts/example/Group/Group_1.ttl +++ /dev/null @@ -1,13 +0,0 @@ -@prefix : <#>. -@prefix vcard: . - -:this - a vcard:Group; - vcard:fn "Group 1"; - vcard:hasMember <../Person/67fca8b3-c74a-499e-b00f-67c543fa533f/index.ttl#this>. - -<../index.ttl#this> vcard:includesGroup :this. - -<../Person/67fca8b3-c74a-499e-b00f-67c543fa533f/index.ttl#this> - vcard:fn "Arne demo 1". - diff --git a/shapes/contacts/example/Group/Group_2.ttl b/shapes/contacts/example/Group/Group_2.ttl deleted file mode 100644 index 53840612..00000000 --- a/shapes/contacts/example/Group/Group_2.ttl +++ /dev/null @@ -1,10 +0,0 @@ -@prefix : <#>. -@prefix vcard: . - -:this - a vcard:Group; - vcard:fn "Group 2". - -<../index.ttl#this> - vcard:includesGroup :this. - diff --git a/shapes/contacts/example/Person/2d73ccc1-9d76-4398-8840-3c23a8ddf04c/index.ttl b/shapes/contacts/example/Person/2d73ccc1-9d76-4398-8840-3c23a8ddf04c/index.ttl deleted file mode 100644 index a6c2f1a1..00000000 --- a/shapes/contacts/example/Person/2d73ccc1-9d76-4398-8840-3c23a8ddf04c/index.ttl +++ /dev/null @@ -1,15 +0,0 @@ -@prefix : <#>. -@prefix dcterms: . -@prefix XML: . -@prefix vcard: . - -<> - dcterms:created "2021-02-04T06:19:42Z"^^XML:dateTime. - -:this - a vcard:Individual; - vcard:fn "Arne H (demo1)"; - vcard:url [ - a vcard:WebID; - vcard:value "https://megoth-demo1.inrupt.net/profile/card#me" - ]. diff --git a/shapes/contacts/example/Person/347429c1-e6b5-40c0-bd6f-61ba1265d357/index.ttl b/shapes/contacts/example/Person/347429c1-e6b5-40c0-bd6f-61ba1265d357/index.ttl deleted file mode 100644 index e3aac88c..00000000 --- a/shapes/contacts/example/Person/347429c1-e6b5-40c0-bd6f-61ba1265d357/index.ttl +++ /dev/null @@ -1,11 +0,0 @@ -@prefix : <#>. -@prefix vcard: . - -:this - a vcard:Individual; - vcard:url :16112499761464744406237652592; - vcard:fn "Vincent". - -:16112499761464744406237652592 - a vcard:WebId; - vcard:value . diff --git a/shapes/contacts/example2/README.md b/shapes/contacts/example/README.md similarity index 95% rename from shapes/contacts/example2/README.md rename to shapes/contacts/example/README.md index 328fa094..43d2795a 100644 --- a/shapes/contacts/example2/README.md +++ b/shapes/contacts/example/README.md @@ -1,7 +1,7 @@ -# Example Turtle files +# Contacts-related Turtle files The example Turtle files here describe the structure and modelling of the -following: +following Contact-related concepts: ### Two address books diff --git a/shapes/contacts/example2/addressBookFriend/index.ttl b/shapes/contacts/example/addressBookFriend/index.ttl similarity index 100% rename from shapes/contacts/example2/addressBookFriend/index.ttl rename to shapes/contacts/example/addressBookFriend/index.ttl diff --git a/shapes/contacts/example2/addressBookWork/index.ttl b/shapes/contacts/example/addressBookWork/index.ttl similarity index 100% rename from shapes/contacts/example2/addressBookWork/index.ttl rename to shapes/contacts/example/addressBookWork/index.ttl diff --git a/shapes/contacts/example2/group/group1-work-colleague.ttl b/shapes/contacts/example/group/group1-work-colleague.ttl similarity index 100% rename from shapes/contacts/example2/group/group1-work-colleague.ttl rename to shapes/contacts/example/group/group1-work-colleague.ttl diff --git a/shapes/contacts/example2/group/group2-friend.ttl b/shapes/contacts/example/group/group2-friend.ttl similarity index 100% rename from shapes/contacts/example2/group/group2-friend.ttl rename to shapes/contacts/example/group/group2-friend.ttl diff --git a/shapes/contacts/example2/group/group3-soccer-team.ttl b/shapes/contacts/example/group/group3-soccer-team.ttl similarity index 100% rename from shapes/contacts/example2/group/group3-soccer-team.ttl rename to shapes/contacts/example/group/group3-soccer-team.ttl diff --git a/shapes/contacts/example2/group/group4-empty.ttl b/shapes/contacts/example/group/group4-empty.ttl similarity index 100% rename from shapes/contacts/example2/group/group4-empty.ttl rename to shapes/contacts/example/group/group4-empty.ttl diff --git a/shapes/contacts/example2/group/index.ttl b/shapes/contacts/example/group/index.ttl similarity index 100% rename from shapes/contacts/example2/group/index.ttl rename to shapes/contacts/example/group/index.ttl diff --git a/shapes/contacts/example/groups.ttl b/shapes/contacts/example/groups.ttl deleted file mode 100644 index e8f573ed..00000000 --- a/shapes/contacts/example/groups.ttl +++ /dev/null @@ -1,16 +0,0 @@ -@prefix : <#>. -@prefix vcard: . - - - a vcard:Group; - vcard:fn "Group 1". - - - a vcard:Group; - vcard:fn "Group 2". - - - vcard:includesGroup - , - . - diff --git a/shapes/contacts/example/index.ttl b/shapes/contacts/example/index.ttl deleted file mode 100644 index ea4ceb6b..00000000 --- a/shapes/contacts/example/index.ttl +++ /dev/null @@ -1,10 +0,0 @@ -@prefix : <#>. -@prefix acl: . -@prefix dcterms: . -@prefix vcard: . - -:this a vcard:AddressBook; - acl:owner ; - dcterms:title "Contacts"; - vcard:nameEmailIndex ; - vcard:groupIndex . diff --git a/shapes/contacts/example/people.ttl b/shapes/contacts/example/people.ttl deleted file mode 100644 index 001dedc6..00000000 --- a/shapes/contacts/example/people.ttl +++ /dev/null @@ -1,10 +0,0 @@ -@prefix : <#>. -@prefix vcard: . - - - vcard:fn "Arne H (demo1)"; - vcard:inAddressBook . - - - vcard:fn "Vincent"; - vcard:inAddressBook . diff --git a/shapes/contacts/example2/person/2d73ccc1-9d76-4398-8840-3c23a8ddf04c/index.ttl b/shapes/contacts/example/person/2d73ccc1-9d76-4398-8840-3c23a8ddf04c/index.ttl similarity index 100% rename from shapes/contacts/example2/person/2d73ccc1-9d76-4398-8840-3c23a8ddf04c/index.ttl rename to shapes/contacts/example/person/2d73ccc1-9d76-4398-8840-3c23a8ddf04c/index.ttl diff --git a/shapes/contacts/example2/person/347429c1-e6b5-40c0-bd6f-61ba1265d357/index.ttl b/shapes/contacts/example/person/347429c1-e6b5-40c0-bd6f-61ba1265d357/index.ttl similarity index 100% rename from shapes/contacts/example2/person/347429c1-e6b5-40c0-bd6f-61ba1265d357/index.ttl rename to shapes/contacts/example/person/347429c1-e6b5-40c0-bd6f-61ba1265d357/index.ttl diff --git a/shapes/contacts/example2/person/76344edd-b1c7-67c2-ec3e-89ab5494e233/index.ttl b/shapes/contacts/example/person/76344edd-b1c7-67c2-ec3e-89ab5494e233/index.ttl similarity index 100% rename from shapes/contacts/example2/person/76344edd-b1c7-67c2-ec3e-89ab5494e233/index.ttl rename to shapes/contacts/example/person/76344edd-b1c7-67c2-ec3e-89ab5494e233/index.ttl diff --git a/shapes/contacts/example2/person/index.ttl b/shapes/contacts/example/person/index.ttl similarity index 100% rename from shapes/contacts/example2/person/index.ttl rename to shapes/contacts/example/person/index.ttl From 70ccd0022653cc8fa95fafc98a670a50ec72038f Mon Sep 17 00:00:00 2001 From: pmcb55 Date: Tue, 9 Feb 2021 22:22:14 +0000 Subject: [PATCH 14/20] typos, feedback from Arne --- shapes/contacts/example/group/group1-work-colleague.ttl | 2 +- shapes/contacts/example/group/group2-friend.ttl | 2 +- shapes/contacts/example/group/group3-soccer-team.ttl | 7 ++++--- shapes/contacts/example/group/group4-empty.ttl | 2 +- 4 files changed, 7 insertions(+), 6 deletions(-) diff --git a/shapes/contacts/example/group/group1-work-colleague.ttl b/shapes/contacts/example/group/group1-work-colleague.ttl index b918a603..00e82418 100644 --- a/shapes/contacts/example/group/group1-work-colleague.ttl +++ b/shapes/contacts/example/group/group1-work-colleague.ttl @@ -3,7 +3,7 @@ prefix vcard: :this a vcard:Group ; - vcard:fn "Group 1" ; + vcard:fn "Group 1 - my work colleagues" ; vcard:hasMember <../Person/2d73ccc1-9d76-4398-8840-3c23a8ddf04c/index.ttl#this> ; vcard:hasMember <../Person/347429c1-e6b5-40c0-bd6f-61ba1265d357/index.ttl#this> . diff --git a/shapes/contacts/example/group/group2-friend.ttl b/shapes/contacts/example/group/group2-friend.ttl index f8fee1f8..3e958cfe 100644 --- a/shapes/contacts/example/group/group2-friend.ttl +++ b/shapes/contacts/example/group/group2-friend.ttl @@ -3,7 +3,7 @@ prefix vcard: :this a vcard:Group ; - vcard:fn "Group 1" ; + vcard:fn "Group 2 - my friends" ; vcard:hasMember <../Person/2d73ccc1-9d76-4398-8840-3c23a8ddf04c/index.ttl#this> ; vcard:hasMember <../Person/347429c1-e6b5-40c0-bd6f-61ba1265d357/index.ttl#this> . diff --git a/shapes/contacts/example/group/group3-soccer-team.ttl b/shapes/contacts/example/group/group3-soccer-team.ttl index f30b7ddf..f01239a6 100644 --- a/shapes/contacts/example/group/group3-soccer-team.ttl +++ b/shapes/contacts/example/group/group3-soccer-team.ttl @@ -3,9 +3,10 @@ prefix vcard: :this a vcard:Group ; - vcard:fn "Group 1" ; - vcard:hasMember <../Person/2d73ccc1-9d76-4398-8840-3c23a8ddf04c/index.ttl#this> ; - vcard:hasMember <../Person/347429c1-e6b5-40c0-bd6f-61ba1265d357/index.ttl#this> . + vcard:fn "Group 3 - local soccer team" ; + vcard:hasMember + <../Person/2d73ccc1-9d76-4398-8840-3c23a8ddf04c/index.ttl#this> , + <../Person/347429c1-e6b5-40c0-bd6f-61ba1265d357/index.ttl#this> . <../addressBookFriend/index.ttl#this> vcard:includesGroup :this . diff --git a/shapes/contacts/example/group/group4-empty.ttl b/shapes/contacts/example/group/group4-empty.ttl index ecb1e57e..31396cec 100644 --- a/shapes/contacts/example/group/group4-empty.ttl +++ b/shapes/contacts/example/group/group4-empty.ttl @@ -4,7 +4,7 @@ prefix vcard: # This is simply an empty group (i.e., no members). :this a vcard:Group ; - vcard:fn "Group 2" . + vcard:fn "Group 4 - empty, for now..." . <../addressBookFriend/index.ttl#this> vcard:includesGroup :this . From 7e1e820e62c1468eca4392900f7a0bcf9f16698b Mon Sep 17 00:00:00 2001 From: pmcb55 Date: Tue, 9 Feb 2021 23:00:12 +0000 Subject: [PATCH 15/20] added details on #this, and quads vs triples --- shapes/README.md | 40 ++++++++++++++++--- shapes/{bookmarks => bookmark}/README.md | 0 shapes/{bookmarks => bookmark}/bookmark.shex | 0 .../example/bookmark/index.ttl | 0 .../{contacts => contact}/address-book.shex | 0 .../{contacts => contact}/example/README.md | 0 .../example/addressBookFriend/index.ttl | 0 .../example/addressBookWork/index.ttl | 0 .../example/group/group1-work-colleague.ttl | 6 ++- .../example/group/group2-friend.ttl | 4 +- .../example/group/group3-soccer-team.ttl | 4 +- .../example/group/group4-empty.ttl | 2 +- .../example/group/index.ttl | 0 .../index.ttl | 0 .../index.ttl | 0 .../index.ttl | 0 .../example/person/index.ttl | 0 shapes/{contacts => contact}/group-index.shex | 0 shapes/{contacts => contact}/group.shex | 0 .../{contacts => contact}/person-index.shex | 0 shapes/{contacts => contact}/person.shex | 0 21 files changed, 46 insertions(+), 10 deletions(-) rename shapes/{bookmarks => bookmark}/README.md (100%) rename shapes/{bookmarks => bookmark}/bookmark.shex (100%) rename shapes/{bookmarks => bookmark}/example/bookmark/index.ttl (100%) rename shapes/{contacts => contact}/address-book.shex (100%) rename shapes/{contacts => contact}/example/README.md (100%) rename shapes/{contacts => contact}/example/addressBookFriend/index.ttl (100%) rename shapes/{contacts => contact}/example/addressBookWork/index.ttl (100%) rename shapes/{contacts => contact}/example/group/group1-work-colleague.ttl (88%) rename shapes/{contacts => contact}/example/group/group2-friend.ttl (96%) rename shapes/{contacts => contact}/example/group/group3-soccer-team.ttl (96%) rename shapes/{contacts => contact}/example/group/group4-empty.ttl (78%) rename shapes/{contacts => contact}/example/group/index.ttl (100%) rename shapes/{contacts => contact}/example/person/2d73ccc1-9d76-4398-8840-3c23a8ddf04c/index.ttl (100%) rename shapes/{contacts => contact}/example/person/347429c1-e6b5-40c0-bd6f-61ba1265d357/index.ttl (100%) rename shapes/{contacts => contact}/example/person/76344edd-b1c7-67c2-ec3e-89ab5494e233/index.ttl (100%) rename shapes/{contacts => contact}/example/person/index.ttl (100%) rename shapes/{contacts => contact}/group-index.shex (100%) rename shapes/{contacts => contact}/group.shex (100%) rename shapes/{contacts => contact}/person-index.shex (100%) rename shapes/{contacts => contact}/person.shex (100%) diff --git a/shapes/README.md b/shapes/README.md index b7a3b69f..6317cac7 100644 --- a/shapes/README.md +++ b/shapes/README.md @@ -1,11 +1,41 @@ # Shapes -## Structure of the Shapes contained here. +This document describes the overall contents of this Shape directory, and +attempts to explain some of the rationale for the modelling. -This directory contains the following sub-directories, each containing ShEx -Shapes and an `/example` folder showing demonstration Turtle files conforming -to the relevant Shapes. The Turtle files are also used to demonstrate how -instances of Pod Resources are expected to be interlinked +## Use of triples versus quads for user data + +Currently our modelling does not use quads for user data at all. + +Instead we propose to use Named Graphs to support various forms of meta-data +that might be associated with any resource, for example, server-managed +meta-data (e.g., the date/time the resource was created or last modified, or +the backend storage node used, etc.), or Access Control List (ACL) data +associated with the resource, or perhaps ShEx shapes the resource must conform +to, or client-side meta-data associated with Non-RDF resources (e.g., the 'name' +of a JPEG image resource, or the camera aperture settings of the image), etc. + +## Structure of the Shapes, and example Turtle contained here. + +This directory contains a `bookmark` directory and a `contact` directory. Each +contains ShEx Shapes and an `/example` folder showing demonstration Turtle files +conforming to the relevant Shapes. + +The Turtle files of the `contact` examples also demonstrate how instances of Pod +Resources are currently interlinked (e.g., it demonstrates groups of people +referenced from address books). + +## Use of the `#this` fragment identifier + +This modelling follows a naming convention whereby the fragment identifier +`#this` can be used to denote the main RDF Subject in the dataset that makes up +all the triples of a single Pod resource. + +For example, in `shapes/contact/example/group/group3-soccer-team.ttl` we use the +`#this` fragment identifier on the RDF Subject of the triples associated with +the Soccer Team Group itself. The resource is free to include triples using as +many other RDF Subjects as it likes, but `#this` is intended to identify the +main entity of the resource. ## Indexes diff --git a/shapes/bookmarks/README.md b/shapes/bookmark/README.md similarity index 100% rename from shapes/bookmarks/README.md rename to shapes/bookmark/README.md diff --git a/shapes/bookmarks/bookmark.shex b/shapes/bookmark/bookmark.shex similarity index 100% rename from shapes/bookmarks/bookmark.shex rename to shapes/bookmark/bookmark.shex diff --git a/shapes/bookmarks/example/bookmark/index.ttl b/shapes/bookmark/example/bookmark/index.ttl similarity index 100% rename from shapes/bookmarks/example/bookmark/index.ttl rename to shapes/bookmark/example/bookmark/index.ttl diff --git a/shapes/contacts/address-book.shex b/shapes/contact/address-book.shex similarity index 100% rename from shapes/contacts/address-book.shex rename to shapes/contact/address-book.shex diff --git a/shapes/contacts/example/README.md b/shapes/contact/example/README.md similarity index 100% rename from shapes/contacts/example/README.md rename to shapes/contact/example/README.md diff --git a/shapes/contacts/example/addressBookFriend/index.ttl b/shapes/contact/example/addressBookFriend/index.ttl similarity index 100% rename from shapes/contacts/example/addressBookFriend/index.ttl rename to shapes/contact/example/addressBookFriend/index.ttl diff --git a/shapes/contacts/example/addressBookWork/index.ttl b/shapes/contact/example/addressBookWork/index.ttl similarity index 100% rename from shapes/contacts/example/addressBookWork/index.ttl rename to shapes/contact/example/addressBookWork/index.ttl diff --git a/shapes/contacts/example/group/group1-work-colleague.ttl b/shapes/contact/example/group/group1-work-colleague.ttl similarity index 88% rename from shapes/contacts/example/group/group1-work-colleague.ttl rename to shapes/contact/example/group/group1-work-colleague.ttl index 00e82418..b04d52d9 100644 --- a/shapes/contacts/example/group/group1-work-colleague.ttl +++ b/shapes/contact/example/group/group1-work-colleague.ttl @@ -9,10 +9,12 @@ prefix vcard: <../addressBookFriend/index.ttl#this> vcard:includesGroup :this . +# # This is caching some data from an external resource by copying it here (just # so that we don't need to fetch each `vcard:hasMember` instance to get their -# vcard:fn values. -<../person/2d73ccc1-9d76-4398-8840-3c23a8ddf04c/index.ttl#this> +# `vcard:fn` values. +# +<../person/`2d73ccc1-9d76-4398-8840-3c23a8ddf04c/index.ttl#this> vcard:fn "Arne - who I work with" . <../person/347429c1-e6b5-40c0-bd6f-61ba1265d357/index.ttl#this> diff --git a/shapes/contacts/example/group/group2-friend.ttl b/shapes/contact/example/group/group2-friend.ttl similarity index 96% rename from shapes/contacts/example/group/group2-friend.ttl rename to shapes/contact/example/group/group2-friend.ttl index 3e958cfe..013a7fca 100644 --- a/shapes/contacts/example/group/group2-friend.ttl +++ b/shapes/contact/example/group/group2-friend.ttl @@ -9,9 +9,11 @@ prefix vcard: <../addressBookFriend/index.ttl#this> vcard:includesGroup :this . +# # This is caching some data from an external resource by copying it here (just # so that we don't need to fetch each `vcard:hasMember` instance to get their -# vcard:fn values. +# `vcard:fn` values. +# <../person/2d73ccc1-9d76-4398-8840-3c23a8ddf04c/index.ttl#this> vcard:fn "Arne - from work, but my mate from D&G" . diff --git a/shapes/contacts/example/group/group3-soccer-team.ttl b/shapes/contact/example/group/group3-soccer-team.ttl similarity index 96% rename from shapes/contacts/example/group/group3-soccer-team.ttl rename to shapes/contact/example/group/group3-soccer-team.ttl index f01239a6..1cb00a19 100644 --- a/shapes/contacts/example/group/group3-soccer-team.ttl +++ b/shapes/contact/example/group/group3-soccer-team.ttl @@ -10,9 +10,11 @@ prefix vcard: <../addressBookFriend/index.ttl#this> vcard:includesGroup :this . +# # This is caching some data from an external resource by copying it here (just # so that we don't need to fetch each `vcard:hasMember` instance to get their -# vcard:fn values. +# `vcard:fn` values. +# <../person/2d73ccc1-9d76-4398-8840-3c23a8ddf04c/index.ttl#this> vcard:fn "Arne - soccer team striker!" . diff --git a/shapes/contacts/example/group/group4-empty.ttl b/shapes/contact/example/group/group4-empty.ttl similarity index 78% rename from shapes/contacts/example/group/group4-empty.ttl rename to shapes/contact/example/group/group4-empty.ttl index 31396cec..20f58dda 100644 --- a/shapes/contacts/example/group/group4-empty.ttl +++ b/shapes/contact/example/group/group4-empty.ttl @@ -1,7 +1,7 @@ prefix : <#> prefix vcard: -# This is simply an empty group (i.e., no members). +# This is simply an empty group (i.e., no members, yet). :this a vcard:Group ; vcard:fn "Group 4 - empty, for now..." . diff --git a/shapes/contacts/example/group/index.ttl b/shapes/contact/example/group/index.ttl similarity index 100% rename from shapes/contacts/example/group/index.ttl rename to shapes/contact/example/group/index.ttl diff --git a/shapes/contacts/example/person/2d73ccc1-9d76-4398-8840-3c23a8ddf04c/index.ttl b/shapes/contact/example/person/2d73ccc1-9d76-4398-8840-3c23a8ddf04c/index.ttl similarity index 100% rename from shapes/contacts/example/person/2d73ccc1-9d76-4398-8840-3c23a8ddf04c/index.ttl rename to shapes/contact/example/person/2d73ccc1-9d76-4398-8840-3c23a8ddf04c/index.ttl diff --git a/shapes/contacts/example/person/347429c1-e6b5-40c0-bd6f-61ba1265d357/index.ttl b/shapes/contact/example/person/347429c1-e6b5-40c0-bd6f-61ba1265d357/index.ttl similarity index 100% rename from shapes/contacts/example/person/347429c1-e6b5-40c0-bd6f-61ba1265d357/index.ttl rename to shapes/contact/example/person/347429c1-e6b5-40c0-bd6f-61ba1265d357/index.ttl diff --git a/shapes/contacts/example/person/76344edd-b1c7-67c2-ec3e-89ab5494e233/index.ttl b/shapes/contact/example/person/76344edd-b1c7-67c2-ec3e-89ab5494e233/index.ttl similarity index 100% rename from shapes/contacts/example/person/76344edd-b1c7-67c2-ec3e-89ab5494e233/index.ttl rename to shapes/contact/example/person/76344edd-b1c7-67c2-ec3e-89ab5494e233/index.ttl diff --git a/shapes/contacts/example/person/index.ttl b/shapes/contact/example/person/index.ttl similarity index 100% rename from shapes/contacts/example/person/index.ttl rename to shapes/contact/example/person/index.ttl diff --git a/shapes/contacts/group-index.shex b/shapes/contact/group-index.shex similarity index 100% rename from shapes/contacts/group-index.shex rename to shapes/contact/group-index.shex diff --git a/shapes/contacts/group.shex b/shapes/contact/group.shex similarity index 100% rename from shapes/contacts/group.shex rename to shapes/contact/group.shex diff --git a/shapes/contacts/person-index.shex b/shapes/contact/person-index.shex similarity index 100% rename from shapes/contacts/person-index.shex rename to shapes/contact/person-index.shex diff --git a/shapes/contacts/person.shex b/shapes/contact/person.shex similarity index 100% rename from shapes/contacts/person.shex rename to shapes/contact/person.shex From e355752636d1b03d6f2b7eedac27d4886ba114b0 Mon Sep 17 00:00:00 2001 From: pmcb55 Date: Wed, 10 Feb 2021 14:36:13 +0000 Subject: [PATCH 16/20] adds question on modelling countries --- shapes/README.md | 43 +++++++++++++++++++++++++++++++++++++++---- 1 file changed, 39 insertions(+), 4 deletions(-) diff --git a/shapes/README.md b/shapes/README.md index 6317cac7..ff9dbc6f 100644 --- a/shapes/README.md +++ b/shapes/README.md @@ -1,13 +1,48 @@ +# Solid User Profile + +We don't currently have a specific Shape defined for user profiles. But the +original Solid specification provides good guidance on the basic requirements +for the Profile Document expected to be returned when de-referencing a WebID. + +See here for details: https://github.com/solid/solid-spec#webid-profile-documents + +We'd certainly be open to ideas on how to model these basic discovery +requirements differently, and also on how to model the actual human user profile +information (such as date-of-birth, gender, address, etc.). + +## The 'country' problem? +An interesting discussion point would be how to model something as seemingly +trivial as the 'country' field of a user's address. If we take the ISO as just +an example of a recognized 'authority' when referring to "countries of the +world" (of course they are by no means the only such authority), then a problem +arises in that the ISO do not provide IRIs for the countries they otherwise +standardize identifiers for (e.g., 'ie' for Ireland, 'de' for Germany). + +(About 7 years ago I specifically asked the ISO if they might consider minting +official IRIs for countries. Their reply was, literally, "**_We do not product +any RDF formats, I am sorry"_**!) + +By way of example of how long-running a fundamental modelling question this is, +see this mailing list thread I started 6 years ago (and specifically see the +guidance from Martin Hepp, re-iterated in the final email from Bernard Vatant), +which basically recommends just using the standardized string values for +countries, and not using IRIs at all(!): +- Martin Hepp: https://lists.w3.org/Archives/Public/public-vocabs/2015Mar/0165.html +- Bernard Vatant (last email): https://lists.w3.org/Archives/Public/public-vocabs/2015Mar/0181.html + # Shapes -This document describes the overall contents of this Shape directory, and -attempts to explain some of the rationale for the modelling. +This remainder of this document describes the overall contents of this +directory, and attempts to explain some of the rationale for the modelling. + +This directory also includes a series of Turtle files demonstrating expected +usage. -## Use of triples versus quads for user data +### Note: Use of triples versus quads for user data Currently our modelling does not use quads for user data at all. -Instead we propose to use Named Graphs to support various forms of meta-data +Instead we propose using Named Graphs to support various forms of meta-data that might be associated with any resource, for example, server-managed meta-data (e.g., the date/time the resource was created or last modified, or the backend storage node used, etc.), or Access Control List (ACL) data From 9070d0932f746e56d58c044c341c051550c6dd27 Mon Sep 17 00:00:00 2001 From: Arne Hassel Date: Wed, 10 Feb 2021 21:02:16 +0100 Subject: [PATCH 17/20] Update shapes/README.md Co-authored-by: Matthieu Bosquet --- shapes/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/shapes/README.md b/shapes/README.md index ff9dbc6f..8f369ae5 100644 --- a/shapes/README.md +++ b/shapes/README.md @@ -32,7 +32,7 @@ countries, and not using IRIs at all(!): # Shapes -This remainder of this document describes the overall contents of this +The remainder of this document describes the overall contents of this directory, and attempts to explain some of the rationale for the modelling. This directory also includes a series of Turtle files demonstrating expected From bd0ab177f6ab47df14fb88a076e32d74283bdffe Mon Sep 17 00:00:00 2001 From: Arne Hassel Date: Wed, 10 Feb 2021 21:02:27 +0100 Subject: [PATCH 18/20] Update shapes/README.md Co-authored-by: Matthieu Bosquet --- shapes/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/shapes/README.md b/shapes/README.md index 8f369ae5..b99f020b 100644 --- a/shapes/README.md +++ b/shapes/README.md @@ -19,7 +19,7 @@ arises in that the ISO do not provide IRIs for the countries they otherwise standardize identifiers for (e.g., 'ie' for Ireland, 'de' for Germany). (About 7 years ago I specifically asked the ISO if they might consider minting -official IRIs for countries. Their reply was, literally, "**_We do not product +official IRIs for countries. Their reply was, literally, "**_We do not produce any RDF formats, I am sorry"_**!) By way of example of how long-running a fundamental modelling question this is, From 99b9acc0cedf3f9d8cff0a5a6f582f189d8b55ef Mon Sep 17 00:00:00 2001 From: pmcb55 Date: Wed, 10 Feb 2021 20:34:18 +0000 Subject: [PATCH 19/20] fixes a couple of typos --- shapes/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/shapes/README.md b/shapes/README.md index b99f020b..4f491b42 100644 --- a/shapes/README.md +++ b/shapes/README.md @@ -19,8 +19,8 @@ arises in that the ISO do not provide IRIs for the countries they otherwise standardize identifiers for (e.g., 'ie' for Ireland, 'de' for Germany). (About 7 years ago I specifically asked the ISO if they might consider minting -official IRIs for countries. Their reply was, literally, "**_We do not produce -any RDF formats, I am sorry"_**!) +official IRIs for countries. Their reply was, literally, "**_We do not product +(sic) any RDF formats, I am sorry"_**!) By way of example of how long-running a fundamental modelling question this is, see this mailing list thread I started 6 years ago (and specifically see the From 41053680fd365f2249c89fb067d22d656fe52e27 Mon Sep 17 00:00:00 2001 From: Matthieu Bosquet Date: Wed, 10 Feb 2021 20:37:38 +0000 Subject: [PATCH 20/20] fix: typos (#248) --- shapes/bookmark/README.md | 2 +- shapes/bookmark/example/bookmark/index.ttl | 6 +++--- shapes/contact/example/group/group1-work-colleague.ttl | 6 +++--- shapes/contact/example/group/group2-friend.ttl | 4 ++-- shapes/contact/example/group/group3-soccer-team.ttl | 4 ++-- shapes/contact/example/person/index.ttl | 6 +++--- 6 files changed, 14 insertions(+), 14 deletions(-) diff --git a/shapes/bookmark/README.md b/shapes/bookmark/README.md index 6aa71a13..deb47192 100644 --- a/shapes/bookmark/README.md +++ b/shapes/bookmark/README.md @@ -2,4 +2,4 @@ Bookmarks are modelled very simply. Due to this simplicity at the moment, we've choosen to model a collection of bookmarks as simply being entities contained -within a single resource (as opposed to defining a resource-per-bookmark). \ No newline at end of file +within a single resource (as opposed to defining a resource-per-bookmark). diff --git a/shapes/bookmark/example/bookmark/index.ttl b/shapes/bookmark/example/bookmark/index.ttl index cbb6f6e3..8d6965ac 100644 --- a/shapes/bookmark/example/bookmark/index.ttl +++ b/shapes/bookmark/example/bookmark/index.ttl @@ -1,16 +1,16 @@ @prefix : <#>. @prefix bookm: . @prefix terms: . -@prefix XML: . +@prefix xsd: . :16115748945888512870652861511 a bookm:Bookmark; - terms:created "2021-01-25T11:41:34.589Z"^^XML:dateTime; + terms:created "2021-01-25T11:41:34.589Z"^^xsd:dateTime; terms:title "Solid Project"; bookm:recalls . :12391230834289702394820340982 a bookm:Bookmark; - terms:created "2021-01-30T12:30:21.321Z"^^XML:dateTime; + terms:created "2021-01-30T12:30:21.321Z"^^xsd:dateTime; terms:title "Inrupt"; bookm:recalls . diff --git a/shapes/contact/example/group/group1-work-colleague.ttl b/shapes/contact/example/group/group1-work-colleague.ttl index b04d52d9..f22c0426 100644 --- a/shapes/contact/example/group/group1-work-colleague.ttl +++ b/shapes/contact/example/group/group1-work-colleague.ttl @@ -4,8 +4,8 @@ prefix vcard: :this a vcard:Group ; vcard:fn "Group 1 - my work colleagues" ; - vcard:hasMember <../Person/2d73ccc1-9d76-4398-8840-3c23a8ddf04c/index.ttl#this> ; - vcard:hasMember <../Person/347429c1-e6b5-40c0-bd6f-61ba1265d357/index.ttl#this> . + vcard:hasMember <../person/2d73ccc1-9d76-4398-8840-3c23a8ddf04c/index.ttl#this> ; + vcard:hasMember <../person/347429c1-e6b5-40c0-bd6f-61ba1265d357/index.ttl#this> . <../addressBookFriend/index.ttl#this> vcard:includesGroup :this . @@ -14,7 +14,7 @@ prefix vcard: # so that we don't need to fetch each `vcard:hasMember` instance to get their # `vcard:fn` values. # -<../person/`2d73ccc1-9d76-4398-8840-3c23a8ddf04c/index.ttl#this> +<../person/2d73ccc1-9d76-4398-8840-3c23a8ddf04c/index.ttl#this> vcard:fn "Arne - who I work with" . <../person/347429c1-e6b5-40c0-bd6f-61ba1265d357/index.ttl#this> diff --git a/shapes/contact/example/group/group2-friend.ttl b/shapes/contact/example/group/group2-friend.ttl index 013a7fca..25c46d37 100644 --- a/shapes/contact/example/group/group2-friend.ttl +++ b/shapes/contact/example/group/group2-friend.ttl @@ -4,8 +4,8 @@ prefix vcard: :this a vcard:Group ; vcard:fn "Group 2 - my friends" ; - vcard:hasMember <../Person/2d73ccc1-9d76-4398-8840-3c23a8ddf04c/index.ttl#this> ; - vcard:hasMember <../Person/347429c1-e6b5-40c0-bd6f-61ba1265d357/index.ttl#this> . + vcard:hasMember <../person/2d73ccc1-9d76-4398-8840-3c23a8ddf04c/index.ttl#this> ; + vcard:hasMember <../person/347429c1-e6b5-40c0-bd6f-61ba1265d357/index.ttl#this> . <../addressBookFriend/index.ttl#this> vcard:includesGroup :this . diff --git a/shapes/contact/example/group/group3-soccer-team.ttl b/shapes/contact/example/group/group3-soccer-team.ttl index 1cb00a19..d480011c 100644 --- a/shapes/contact/example/group/group3-soccer-team.ttl +++ b/shapes/contact/example/group/group3-soccer-team.ttl @@ -5,8 +5,8 @@ prefix vcard: a vcard:Group ; vcard:fn "Group 3 - local soccer team" ; vcard:hasMember - <../Person/2d73ccc1-9d76-4398-8840-3c23a8ddf04c/index.ttl#this> , - <../Person/347429c1-e6b5-40c0-bd6f-61ba1265d357/index.ttl#this> . + <../person/2d73ccc1-9d76-4398-8840-3c23a8ddf04c/index.ttl#this> , + <../person/347429c1-e6b5-40c0-bd6f-61ba1265d357/index.ttl#this> . <../addressBookFriend/index.ttl#this> vcard:includesGroup :this . diff --git a/shapes/contact/example/person/index.ttl b/shapes/contact/example/person/index.ttl index 873edf50..878f0094 100644 --- a/shapes/contact/example/person/index.ttl +++ b/shapes/contact/example/person/index.ttl @@ -8,16 +8,16 @@ prefix vcard: # can cache (or copy) specific data from each person to here in this index too # (so that we can access that data without having to read all the individual # people resources when just listing all the people with their names). - + vcard:fn "Arne H" ; vcard:inAddressBook <../addressBookFriend/index.ttl#this> , <../addressBookWork/index.ttl#this> . - + vcard:fn "Vincent" ; vcard:inAddressBook <../addressBookWork/index.ttl#this> . - + vcard:fn "Tommy Mc" ; vcard:inAddressBook <../addressBookFriend/index.ttl#this> .