diff --git a/notes/dataDiscovery.md b/notes/dataDiscovery.md index a94ba88..cab7b35 100644 --- a/notes/dataDiscovery.md +++ b/notes/dataDiscovery.md @@ -12,30 +12,40 @@ An app can discover the general location of a WebID owner's data by finding the ### Discoverying Type Indexes 1. An app SHOULD look in the Profile Document (WebID or Extended profile documents) or in the Preference File for a triple that contains the `solid:publicTypeIndex` or the `solid:privateTypeIndex` predicate. -2. If a triple is not found, the app MAY offer to create the triple and the Type Index Registry. See example at [Type Index Resource links example](#type-index-resource-links-example). -3. If the triple is found, the app SHOULD load the object of that triple, which MUST look like (`setting/publicTypeIndex.ttl` or `settings/privateTypeIndex`) +2. If a triple is not found, the app MAY offer to create the triple and the Type Index document. See example at [Type Index section for examples](./typeIndex.md#examples). +3. If the triple is found, the app SHOULD load the object of that triple, which is the Type Index document. ## Data reading An app interested in reading data stored by itself or other apps SHOULD read the [Type Indexes](./typeIndex.md) to find the data location(s) and types of data. -Assuming a Type Index Registry resource exsits: +Assuming a Type Index document exsits: -1. The app MUST load the resource. +1. The app MUST load the document. 2. The app SHOULD read the Type Index registration entries which are of type `solid:TypeRegistration`. Further, each entry MAY maps to a Solid resource or a Solid container described by triples that contain `solid:instance` and/or `solid:instanceContainer`. ## Data writing -An app that writes data SHOULD use the [Type Indexes](./typeIndex.md) to register information about where it writes the specific data and what type of data it writes. +An app that writes data SHOULD use the Type Indexes to register information about where it writes the specific data and what type of data it writes. -Assuming a Type Index Registry resource exsits: +Assuming a Type Index document exsits: -1. The app MUST load the resource. +1. The app MUST load the document. 2. The app MUST write a triple of type `solid:TypeRegistration`. -3. The same triple SHOULD map to a Solid resource and/or a Solid container by writing triples that contain the predicates `solid:instance` and respectively `solid:instanceContainer`. See example at [Type Index Registry Resource content](#type-index-registry-resource-content) +3. The same triple SHOULD map to a Solid resource and/or a Solid container by writing triples that contain the predicates `solid:instance` and respectively `solid:instanceContainer`. See example at [Type Index section for examples](./typeIndex.md). + +If there is no Type Index document, refer to the [Handling missing type indexes section](#Handling-missing-type-indexes). ## Changing privacy of data -Changing the privacy of data involves working with the private and public [Type Indexes](./typeIndex.md). +Changing the privacy of data involves working with the private and public Type Indexes. The app MUST change the status of a registration entry in the Type Index. This involves *removing* that registration entry (typically via a SPARQL-based HTTP PATCH) from the one and *adding* it (also via a PATCH) to the other type index document. + +## Handling missing Type Indexes + +If there is no Type Index, assuming the app writes a specific type of data, it SHOULD create a Type Index. The following steps are recommended: + +1. Ask the WebID owner if the data to be written is public or private and create the according link as mentioned in the [Where to find the Type Indexes](./typeIndex.md#where-to-find-the-type-indexes). +2a. For a public Type Index document, create the document with the specification mentioned under [Public Type Index](./typeIndex.md#public-type-index-usually-called-publictypeindexttl). +2b. For a private Type Index document, create the document with the specification mentioned under [Private Type Index](./typeIndex.md#private-type-index-usually-called-privatetypeindexttl). diff --git a/notes/typeIndex.md b/notes/typeIndex.md index 8fa7537..c1245aa 100644 --- a/notes/typeIndex.md +++ b/notes/typeIndex.md @@ -2,29 +2,29 @@ ## What is a Type Index? -To interact with data, the app needs to know what type of data the WebID owner has and where to find it. For this purpose, the Type Indexes SHOULD exit. +A Type Index is a document containing statements that link specific types of data to specific locations. An app might ask a user where they want to store items of type Bookmark and then write that location in the Type Index. Thereafter another app can find the bookmarks by looking for the location in the Type Index. -A well-behaved profile will include exactly one public Type Index (readable by all) called `publicTypeIndex.ttl` and one private Type Index (readable only be apps acting on behalf of the WebID owner) called `privateTypeIndex.ttl`. +Well-behaved apps will always read from and write to the Type Index so that the user's choices are remembered. Since users will undoubtedly have data they want to keep private, there are two Type Indexes - one readable by any app (publicly discoverable) and one only readable by apps operating on behalf of the WebID owner (not publicly discoverable). ## Where to find the Type Indexes -To find the Type Indexes, an app SHOULD load Profile Document (WebID document, WebID Helper Document, Extended profile document) or the Preference File. In these loaded documents one can find triples where the WebID as subject and the following predicates: for the Public Type Index document the `solid:publicTypeIndex` predicate, and for the Private Type Index document the `solid:privateTypeIndex` predicate. +To find the Type Indexes, an app SHOULD load the Profile Document (WebID document, WebID Helper Document, Extended profile document) or the Preference File. In these loaded documents one can find triples where the WebID as subject and the following predicates: for the Public Type Index document the `solid:publicTypeIndex` predicate, and for the Private Type Index document the `solid:privateTypeIndex` predicate. ### Examples -An example for a Public Type Index Resource linked from the profile is: +An example for a Public Type Index Resource that is located in `settings` and is called `publicTypeIndex.ttl` linked from the profile is: ``` - <#WebID> . + <#WebID> . ``` -An example for a Private Type Index Resource linked from the profile is: +An example for a Private Type Index Resourcelocated in `settings` and is called `privateTypeIndex.ttl` linked from the profile is: ``` - <#WebID> . + <#WebID> . ``` Here is a diagram showing an example set of Type Indexes: ![Type Registry Index diagram](../diagrams/type-indexes.svg) -## Public Type Index (publicTypeIndex.ttl) +## Public Type Index (usually called publicTypeIndex.ttl) The Public Type Index document MUST be of type `solid:ListedDocument` and `solid:TypeIndex`. @@ -51,7 +51,7 @@ Example of a Public Type Index document. This contains a public resource of type solid:instance . ``` -## Private Type Index (privateTypeIndex.ttl) +## Private Type Index (usually called privateTypeIndex.ttl) The Private Type Index document contains registration entries that are private to the user and their apps, for types that are *not* publicly discoverable. @@ -88,5 +88,6 @@ maps a type to an individual Solid *resource*, typically an index or a directory ##### `solid:instanceContainer` maps a type to a Solid *container* which the client would have to list to get the instances of that type. + ## Reference * [link 1](https://github.com/solid/solid/blob/main/proposals/data-discovery.md) \ No newline at end of file