search

solid / type-indexes

About Type Indexes and how they can be used by Solid developers.
https://solid.github.io/type-indexes/
MIT License
7 stars 3 forks source link

Consider revising Type Indexes section #16

Open csarven opened 1 year ago

csarven commented 1 year ago

Re #type-indexes

A Type Index is a document containing statements that link specific types of data to specific locations.

Perhaps add "..specific locations in a storage".

An app might ask a

Aha! Now the "app" makes its appearance :) See also https://github.com/solid/type-indexes/issues/13 about clarifying whether it is "client" or "application" that plays a central role in the specification.

user where they want to store items of type Bookmark and then write that location in the Type Index.

Good. Perhaps mention the term in brackets after "type Bookmark (foo:Class)" if it is intended to be a hint to a specific kind of bookmark class, or alternatively link to a section or thing somewhere else in the document that the reader can learn more about it.

Thereafter another app can find the bookmarks by looking for the location in the Type Index.

See, here "find" (or possibly discover) is a good term that should bubble up its way into introduction. Then the reader can follow the idea from the Introduction to this section.

Apps that want to remember user's choices will read from and write to the Type Index.

Okie.

Since users will undoubtedly have data they

Consider using "Users typically 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).

Okie.

To find Type Indexes, an app SHOULD load the WebID Profile Document and if the app has access, also the Preferences Document.

Consider having a subsection "Discovery" (as the first subsection of Type Indexes) and move this and related information there.

Add more detail about application behaviour when they discover multiple public/privateTypeIndex properties, and whether the application should use one (that it prefers) or all.

Split considerations on access permissions to somewhere else so that conformance clauses do not need to include them. It it always going to be the case, including the loading of the Preferences Document (if the app has access).

Consider clarifying or defining what "load(ing)" entails. Is it "fetching" a representation, "parsing", and having a usable "object" of sorts?

If finding Type Indexes through the WebID Profile Document and or the Preferences Document is a core requirement for an application so that there is interoperability, consider changing the requirement to should. It reads like the Preferences Document may not be, but then at least the WebID Profile Document MUST be. If there is no MUST here, then there is no significant implementation to talk about.

In these loaded documents one can find triples where the WebID is the subject and predicates can be: for the Public Type Index document a solid:publicTypeIndex predicate, and for the Private Type Index document a solid:privateTypeIndex predicate.

Okie.

Re:

<div datatype="rdf:HTML" property="schema:description">
            <section
              id="public-type-index"

I think the content/HTML before the div wrapper can be moved inside it. So, it becomes:

section type-indexes
  h2
  div
    section public-type-indexes
      h3
      div

The code examples mention UnlistedDocument and TypeIndex classes. They should be introduced/acknowledged in the Type Indexes (or another) section.

Before the examples, explain the data model like in https://github.com/solid/type-indexes/issues/18