Specification core concepts

[timea-solid]

The extracted requirements are for now:

• $\textcolor{orange}{\textsf{App}}$ SHOULD load the $\textcolor{orange}{\textsf{WebID Profile Document}}$.
• $\textcolor{orange}{\textsf{App}}$ SHOULD load the $\textcolor{orange}{\textsf{Preference Document}}$ (if it has access).
• $\textcolor{orange}{\textsf{App}}$ MAY warn $\textcolor{orange}{\textsf{the user of the app}}$ that the public/private type index is missing. (if it has access to private TY).
• $\textcolor{orange}{\textsf{App}}$ MAY create $\textcolor{orange}{\textsf{missing type index docs}}$ (Private TY if according to the access level present).
• $\textcolor{orange}{\textsf{The Public Type Index}}$ SHOULD be publicly readable and only writable by $\textcolor{orange}{\textsf{the user (or group delegated by the user)}}$.
• $\textcolor{orange}{\textsf{A pointer to the Public Type Index}}$ MUST be placed in the $\textcolor{orange}{\textsf{WebID Profile Document}}$.
• $\textcolor{orange}{\textsf{The Private Type Index}}$ SHOULD be readable and writable only by $\textcolor{orange}{\textsf{the WebID owner}}$.
• $\textcolor{orange}{\textsf{A pointer to the Private Type Index}}$ MUST be placed n the $\textcolor{orange}{\textsf{WebID Profile Document}}$.
• The $\textcolor{orange}{\textsf{Type Index documents}}$ MAY contain any number of statements of type solid:TypeRegistration.
• The $\textcolor{orange}{\textsf{Registration Entries}}$ map a type to a location and MUST use one of 2 predicates: solid:instance or solid:instanceContainer.

But the above is still ambiguous (who is the app?) and is not using concepts in line with the dimension variability.
To better break down the above requirements the following concepts were identified:
Above, we name an app something that can:

• load documents -> to align to dimension variability this would be a player/consumer
• warn user -> producer of instructions
• create missing Type Index -> producer of content

Above, we name a user someone who:

• is a webId owner -> is a logged in user who has a webId profile document
• user of app -> logged in user to the storage - user with according access level allowed to load resources
• writable by user
• readable by user

Next, we exemplify how the rewording of the text would look like:

• We distinguish between public users and logged-in users. Logged-in users represent those users who have or have been given permission to write/append/delete specific private resources.

• We also distinguish between WebId Owner and logged-in users. The WebID owner has ultimate permissions on all resources. Logged-in users, might only be authorized on specific resources.

• From now on we call a WebId owner the logged-in user who has read/write/append/delete rights on all resources. We call a logged-in user, those users who are logged in and have the correct permission level to read/write/append/delete specific resources. We call public users, those users who are not logged in and can read public resources.

• All types of users make use of an application to read or modify resources. This application has different facets:

• a consumer application we call the group of features of the application that read resources.

• a producer of content application we call the group of features of the application that write or append (sometimes delete) resources

• a producer of instructions application we call the group of features of the application that alert/notify the user of the application in some way.

And the requirements would transform as:

• $\textcolor{orange}{\textsf{A logged-in user using a consumer application}}$ SHOULD load the $\textcolor{orange}{\textsf{WebID Profile Document}}$.
• $\textcolor{orange}{\textsf{A logged-in user using a consumer application}}$ SHOULD load the $\textcolor{orange}{\textsf{Preference Document}}$ (if it has access).
• $\textcolor{orange}{\textsf{The application}}$ MAY warn $\textcolor{orange}{\textsf{the user of the app}}$ that the public/private type index is missing. (if it has access to private TY).
• $\textcolor{orange}{\textsf{A logged-in user using a producer of content application}}$ MAY create $\textcolor{orange}{\textsf{missing type index docs}}$.
• $\textcolor{orange}{\textsf{The Public Type Index}}$ SHOULD be publicly readable and only writable by $\textcolor{orange}{\textsf{a logged in user }}$.
• $\textcolor{orange}{\textsf{A pointer to the Public Type Index}}$ MUST be placed in the $\textcolor{orange}{\textsf{WebID Profile Document}}$.
• $\textcolor{orange}{\textsf{The Private Type Index}}$ SHOULD be readable and writable only by $\textcolor{orange}{\textsf{the WebID owner}}$.
• $\textcolor{orange}{\textsf{A pointer to the Private Type Index}}$ MUST be placed n the $\textcolor{orange}{\textsf{WebID Profile Document}}$.
• The $\textcolor{orange}{\textsf{Type Index documents}}$ MAY contain any number of statements of type solid:TypeRegistration.
• The $\textcolor{orange}{\textsf{Registration Entries}}$ map a type to a location and MUST use one of 2 predicates: solid:instance or solid:instanceContainer.

[jeff-zucker]

These conformance rules all seem appropriate to me. It may be worth noting that previous outdated drafts recommended that the privateTypeIndex triple be placed in the preferencesFile rather than the WebID-profile document and that recommendation no longer applies.

[timea-solid]

@jeff-zucker I restructured ad reworded the discussion. I think it was not clear what I wanted to achieve. Please read again.

[csarven]

Great. This looks like in the right direction! I like that you are breaking down the classes of products and interoperability among them. Some comments:

Generally type-indexes should align/reuse all definitions from Solid WebID Profile, e.g., app, user. So if need be, some of this info can move that spec. It is okay to consider these terms from the point of multiple specs, and then settle on one that'd representative for them, then just have them be defined there. On that note, Solid Protocol defines https://solidproject.org/ED/protocol#solid-app , so we can look into whether that definition needs an update i) in Solid Protocol, ii) reused, specialised/extended, or defined differently in Solid WebID Profile, iii) reused, specialised/extended, or defined differently in Solid Type Indexes. Reusing Solid Protocol's may be sufficient. (Let's come back to this.) Ditto "user" and other terms.

That'd would generally leave the other specs to express the interop between the products, e.g., "app" and "storage".

See also those concepts in http://www.w3.org/ns/spec (copied form spec-variability) but it need not be limited to them. For example, https://solid.github.io/notifications/protocol#SubscriptionServer is a concept has broadMatches to RespondingAgent and ProducerOfInstructions.

Regarding "user", consider also distinguishing between an identifiable or anonymous (or pseudonymous) social agent. I think Solid WebID Profile has something to say about that.

We distinguish between public users and logged-in users. Logged-in users represent those users who have or have been given permission to write/append/delete specific private resources.

It is possible that only logged-in users (AuthenticatedAgent) can read.

We also distinguish between WebId Owner and logged-in users. The WebID owner has ultimate permissions on all resources. Logged-in users, might only be authorized on specific resources.

Did you mean https://solidproject.org/ED/protocol#owner instead of "WebId Owner"?

From now on we call a WebId owner the logged-in user who has read/write/append/delete rights on all resources. We call a logged-in user, those users who are logged in and have the correct permission level to read/write/append/delete specific resources. We call public users, those users who are not logged in and can read public resources.

I think it possible for public users to write/append (e.g., to containers).

Let me make a clear distinction here between the general role / abilities of a public user and one defined in Solid Type Indexes. So, for example, a public user could technically write/append to resources, Solid Type Indexes could very well set a limitation and say a public user cannot write/append to resources. So, Solid WebID Profile should provide the broader definition, and if Solid Type Indexes can reuse it as is, great, but if it needs to set something else for comformance, that'd be fine too.

a producer of content application we call the group of features of the application that write or append (sometimes delete) resources

a producer of instructions application we call the group of features of the application that alert/notify the user of the application in some way.

I like these. I think if alert/notify is useful to mention as part of conformance, consider whether providing a "view" should be incorporated into "producer of content" (which is at the moment in the context of a resource).

I like the definition but I'd also like to suggest to limit the definition to the category of requirements that'd be expected from there application. For example, think along these lines: will there be a requirement in the Solid Type Indexes specification that says something like "The application MUST alert the user to reset the document view, when the user agent receives a 205 status code in response to a new Type Registration."

Regarding the listed requirements, I'd suggest to separate between a set of protocol/discovery/behaviour level requirements from the data shape of certain resources. For example:

The MAY contain any number of statements of type solid:TypeRegistration.

could be part of describing the Type Index document (below is just examples.. determine exactly what the shape is towards interop. Re #18 ):

• One rdf:type whose object is solid:TypeIndex.
• ...

Describing TypeRegistration:

• One rdf:type property whose object is solid:TypeRegistration.
• One solid:forClass property whose object is a class of the resource type.
• One solid:instance ...

Similarly, stuff like:

A pointer to the Public Type Index MUST be placed in the WebID Profile Document

should turn into (I'm assuming WebID or WebID Profile is intended as opposed to WebID Profile Document with respect to a shape):

WebID:

• One solid:publicTypeIndex property to refer to the location of the public Type Index Document.

See example shapes in https://solidproject.org/ED/qa#test-case-description , https://solid.github.io/notifications/protocol#notification-channel-data-model , https://solidproject.org/ED/protocol#contained-resource-metadata-statements , https://solidproject.org/TR/wac#authorization-conformance

All other requirements related to the protocol, i.e., describing behaviour related to read-write requests, can stay as is (along the lines you have now):

The Private Type Index SHOULD be readable and writable only by the WebID owner.

Aside: the (orange) colouring of the text is neat but somehow selecting the text of the whole line is prevented for me (on Firefox).

[timea-solid]

Thank you for the feedback.

Let's clarify the classes of products needed.
We cannot take 1 on 1 the classes of products from WebId profile because they talk about WebID profile content reading and writing only. The application mentioned in the Type index can read and write any data on a storage. So here are the new Type Index product classes, inspired by the WebId Profile spec:

• Reader Application (above-named consumer application)
  A Solid app that only reads data from one or more storages.

• Writer Application (above-named producer of content)
  A Solid app that writes, appends, or deletes data from one or more storages.

• View Application (above-named producer of instructions)
  A Solid app that can display notifications or information to the application user.

While the naming of reader and writer applications is clear, I'd like to clarify the need for the view application.
We have the following requirement: $\textcolor{orange}{\textsf{App}}$ MAY warn $\textcolor{orange}{\textsf{the user of the app}}$ that the public/private type index is missing. (if it has access to private TY). This requirements prompts me to have a specific requirement like:
A view application MAY warn the user of the app that the public/private type index is missing (getting a 404 upon trying to read the TY).

What do we think about the proposed classes of products?

[woutermont]

Is the App in that requirement anything else than either a Reader App or a Writer App? 🤔

[timea-solid]

The feature of "warning the user" is neither a read nor a write from my perspective. The reason why I propose a View Application.

[woutermont]

Yes, the feature/requirement is different, but does it ever apply to products that do not fall in either the Reader or Writer classes? If not, then no separate class needs to be described.

[timea-solid]

I see. I interpreted it differently however there is no need of another. I can just say Solid application (regardless what kind it is).

[woutermont]

I mean, it could be useful to have an umbrella class, but then that should be clear in the description.