Align shared core terminology

[woutermont]

Solid now contains a number of drafts that each include a terminology section defining the terms necessary for their discourse. On the borders where they interface (and sometimes overlap a bit), some terms are defined in multiple specifications. Sometimes these definitions are rather different, which makes the overal discourse confusing. At other times, the definitions are similar or identical, but this still presents a problem for maintenance. As discussed in the meeting of August 16th, I will use this issue to provide an overview and comparison of the concerning definitions, and propagate conclusions to the relevant panels.

[woutermont]

Uniform Resource Identifier

• [SOLID-PROTOCOL]: A Uniform Resource Identifier (URI) provides the means for identifying resources [RFC3986].
• [WAC] literally copies the above.
• [SOLID-OIDC] uses the term, but does not define it, nor does it refer to a definition in another document.
• [RFC3986] defines a URI as an identifier matching a specified syntax rule: a compact sequence of characters that identifies an abstract or physical resource.

Suggestions:

• Remove the definition from WAC, just borrow from and refer to Protocol.
• Either remove the definition from Protocol and simply borrow from and refer to RFC3986, or make the definition more informative; for example: A Uniform Resource Identifier (URI) is an identifier as defined in [RFC3986], used to identify an entity in a global context.
• Borrow from and refer to Protocol from Solid-OIDC.

[TallTed]

I like A Uniform Resource Identifier (URI) is an identifier as defined in [RFC3986], used to identify an entity in a global context.

[woutermont]

Resource

• [SOLID-PROTOCOL]: A resource is the target of an HTTP request identified by a URI [RFC7231].
• [WAC] literally copies the above.
• [ACP] borrows the term from [RDF]
• [SOLID-OIDC] uses the term, but does not define it, nor does it refer to a definition in another document.
• [RFC7231] states that [t]he target of an HTTP request is called a "resource", NOT that each resource is such a target: HTTP does not limit the nature of a resource; it merely defines an interface that might be used to interact with resources.
• [RFC3986] and [WEBARCH] define a resource as anything that might be identified by a URI, without further limiting its scope.
• [RDF] states: Anything can be a resource ... the term is synonymous with 'entity' as it is used in [RDF12-SEMANTICS]. It holds that anything in the universe of discourse is a resource, including those values denoted by literals.

Suggestions:

• Correct this problematic definition, since it is neither what is specified in RFC7231, nor is it consistent with "resource" as mentioned in the definition of URI. Resources are broader than HTTP targets, and we want to use the term in this broad way; otherwise we end up avoiding it in convoluted sentences as "an Authorization is an abstract thing which is identified by a URI" [WAC]), and using it in different ways between specs (WAC/Protocol vs ACP). One approach is to clearly distinguish when we're talking about HTTP and when not:
  • A resource is anything that might be identified by a URI, as defined in [RFC3986].
  • An HTTP resource is a resource that can be the target of an HTTP request, identified by an URI with the http or https scheme. [RFC9110]
• Refer to RFC9110 instead of the obsolete RFC7231 (see Refer rfc 9110, over obsolated 7230, 7231, 7232, 7233, 7235, 7538, 7615, 7694 #471).
• Once made consistent, remove the definition from WAC and ACP, just borrow from and refer to Protocol.
• Borrow from and refer to Protocol from Solid-OIDC.

[TallTed]

Note that RDF restricts its URIs to the HTTP/S scheme, but it does not require that these URIs resolve to anything, nor even that there be an HTTP/S server answering that authority... Therefore, maybe —

A resource, synonymous with entity as it is used in [RDF12-SEMANTICS], is anything that might be identified by a URI, as defined in [RFC3986]. An HTTP resource is identified by an URI in the http or https scheme [RFC9110], and can be the target of an HTTP request.

[woutermont]

Container (resource)

• [SOLID-PROTOCOL]: A container resource is a hierarchical collection of resources that contains other resources, including containers.
• [WAC] literally copies the above.
• [LDP] defines an LDP Container as [an LDP RDF Source] representing a collection of linked documents (RDF Document [rdf11-concepts] or information resources [WEBARCH]) that responds to client requests for creation, modification, and/or enumeration of its linked members and documents, and that conforms to the simple lifecycle patterns and conventions in [LDP].

Suggestions:

• Remove the definition from WAC, just borrow from and refer to Protocol.
• As long as we are using LDP, we can just as well borrow from and refer to LDP.

[csarven]

I'm not sure about "borrow" how per se but it needs to be clear enough because WAC doesn't (or intended to) depend on SOLID-PROTOCOL. They share the same notion of hierarchical collection of resources. SOLID-PROTOCOL may be using LDP but WAC is left open such that it could be used alongside e.g., LDP, SOLID-PROTOCOL, or ACTIVITYPUB (in which case the notion is "Collection" from AS2).

[TallTed]

The SOLID-PROTOCOL (and WAC) definition has problems. Empty containers must be permitted, among other things. This might be a viable revision —

A container (or container resource) is a resource that may contain other resources, including other containers, typically found in a hierarchical collection of resources and their container(s).

[TallTed]

and "WAC doesn't (or intended to) depend on SOLID-PROTOCOL" but "[WAC] literally copies" from [SOLID-PROTOCOL]. This suggests to me that there ought to be another spec (that needs to reach TR, as quickly as possible) which both [WAC] and [SOLID-PROTOCOL] can then normatively reference.

[woutermont]

Root container

• [SOLID-PROTOCOL]: a container resource that is at the highest level of the collection hierarchy.
• [WAC] literally copies the above.

Suggestions:

• Remove the definition from WAC, just borrow from and refer to Protocol.

[csarven]

I'm not sure about "borrow" how per se but it needs to be clear enough because WAC doesn't (or intended to) depend on SOLID-PROTOCOL.

[TallTed]

"WAC doesn't (or intended to) depend on SOLID-PROTOCOL" but "[WAC] literally copies" from [SOLID-PROTOCOL]. This suggests to me that there ought to be another spec (that needs to reach TR, as quickly as possible) which both [WAC] and [SOLID-PROTOCOL] can then normatively reference.

[woutermont]

(Web) agent

• [SOLID-PROTOCOL]: An agent is a person, social entity, or software identified by a URI; e.g., a WebID denotes an agent.
• [WAC] literally copies the above.
• [SAI]: Agents are the primary actors in an interoperable Solid ecosystem ... Agents are denoted by an identity. It distinguishes Social Agents and Applications as specific distinct types of Agents.
• [SOLID-OIDC] uses the term, but does not define it, nor does it refer to a definition in another document.
• [WEBARCH] defines a "Web agent" as a person or a piece of software acting on the information space on behalf of a person, entity, or process.

Suggestions:

• Align definitions: scrap 'person' from Protocol definition, since this is included in 'social entity', and correct SAI's use of 'identity': agents are denoted by 'identifiers'; for example: A Web agent, or 'agent' for short, is an entity acting on the Web. A main distinction is made between two agent classes: social agents, acting on behalf of themselves, and software agents, acting on behalf of another agent [WEBARCH]. Within the context of Solid, every agent is identified by a URI.
• After alignment, remove the definition from WAC and SAI, just borrow from and refer to Protocol.
• Borrow from and refer to Protocol from Solid-OIDC.

---

We could possibly also add definitions for agent groups, agent classes, social agents and software agents to the Protocol, since they are pretty central in authn, authz and interop.

[TallTed]

Perhaps —

A Web agent, or 'agent' for short, is an entity acting on the Web. There are two primary agent classes: social agents, acting on behalf of themselves or another social agent; and software agents, acting on behalf of another social or software agent [WEBARCH]. Within the context of Solid, every agent is identified by a URI, typically but not always a WebID.

[woutermont]

Resource server (RS) [role]

• [SOLID-PROTOCOL]: A server that builds on HTTP server [RFC7230] and [RFC7231] by defining media types, HTTP header fields, and the behaviour of resources, as identified by link relations.
• [SOLID-NOTIFICATIONS] literally copies the above.
• [SAI] defines a "server-side applications" as applications that run on a dedicated server which may also act as autonomous authenticated agents.
• [SOLID-OIDC] borrows the term from [OAUTH].
• [RFC7230] defines an HTTP server as a program that accepts connections in order to service HTTP requests by sending HTTP responses: A server responds to a client's request by sending one or more "response" messages, each including a status code. It emphasizes that the term only refers to the role the program performs for a particular connection.
• [OAUTH] defines the resource server role as the server hosting the protected resources, capable of accepting and responding to protected resource requests using access tokens.

Suggestions:

• Remove the 'server' definition from Protocol. It contains nothing more than an HTTP server with some emphasis on its extensibility.
• Instead, add a definition of 'resource server' to Protocol; for example: A resource server is an HTTP server [RFC9110] that hosts protected resources, defines the behaviour of those resources using link relations [RFC8288], and is capable of accepting and responding to access requests to those resources.
• Refer to RFC9110 instead of the obsolete RFC7231 (see Refer rfc 9110, over obsolated 7230, 7231, 7232, 7233, 7235, 7538, 7615, 7694 #471).
• Remove the definition of 'resource server' from Notifications, and borrow from and refer to Protocol.
• Repurpose the definition of 'server-side applications' in SAI to more clearly concern autonomous software agents.

[woutermont]

(Solid) pod, storage

• [SOLID-PROTOCOL]: A storage is a space of URIs that affords agents controlled access to resources.
• [SAI]: A Solid pod is a place for storing and accessing data via the Solid protocol, with mechanisms for controlling who or what can access that data.
• [SOLID-NOTIFICATIONS] and [WAC] both use the term but do not define it, nor do they refer to a definition in another document.

Suggestions:

• Decide whether we still want to use the term 'pod', and if so, whether it is equal to the term 'storage'. For the further points, I assume that they are terms for the same thing.
• Decide whether the term(s) refer to the resource, or to the namespace.
• Align definitions; for example: A storage, a.k.a. a Solid pod, is service offering controlled access to a set of resources, identified by a common URI namespace, that are owned and controlled by the same (social) agent.
• After alignment, remove definition from [SAI] and instead borrow from and refer to Protocol.
• Borrow from and refer to Protocol from Notifications and WAC.

[csarven]

Strange.. We must've missed SAI (perhaps that part of the spec is a bit outdated). We did come to the understanding that "pod" is not a clear enough term in Solid TRs, where what's usually intended in its context is either "storage" or "server" (or both), and those are already well-defined and has conformance. See e.g., #475 (and referenced issue). "Pod" can still be generally used in other kinds of content, usually informally, i.e., outside of specifications.

[woutermont]

Client (application) [role]

• [SOLID-PROTOCOL]: A client that builds on HTTP client [RFC7230], [RFC7231], and [FETCH] by defining behaviour in terms of fetching across the platform.
• [SOLID-PROTOCOL] also defines a "Solid app": A Solid app is an application that reads or writes data from one or more storages.
• [SOLID-NOTIFICATIONS] copies the above it its definitions of the Discovery Client and Subscription Client classes.
• [SOLID-OIDC] borrows the term from [OAUTH].
• [RFC7230] defines an HTTP client as a program that establishes a connection to a server for the purpose of sending one or more HTTP requests: A client sends requests to a server in the form of a "request" message with a method and request target. It emphasizes that the term only refers to the role the program performs for a particular connection.
• [OAUTH] defines the role 'client' as an application making protected resource requests on behalf of the resource owner and with its authorization ... [it] does not imply any particular implementation characteristics (e.g., whether the application executes on a server, a desktop, or other devices).

Suggestions:

• Decide whether there is a difference between a client application and a Solid app. In the following points, I assume there is not.
• Remove the definition of a "Solid app" from Protocol, replacing it with "client application".
• Align definitions; for example: A client (application) is an HTTP client conforming to [FETCH], accessing resources at one or more storages on behalf of another agent, and with the authorization of the resource owner(s).
• Refer to RFC9110 instead of the obsolete RFC7230 and RFC7231 (see Refer rfc 9110, over obsolated 7230, 7231, 7232, 7233, 7235, 7538, 7615, 7694 #471).
• Provide more informative definitions for Notification's Discovery Client and Subscription Client classes.
• Borrow from and refer to Protocol from Solid-OIDC.

[woutermont]

Resource owner (RO)

• [SOLID-PROTOCOL]: An owner is a person or a social entity that is considered to have the rights and responsibilities of a storage. An owner is identified by a URI, and implicitly has control over all resources in a storage. An owner is first set at storage provisioning time and can be changed.
• [OAUTH] defines the resource owner role: An entity capable of granting access to a protected resource. When the resource owner is a person, it is referred to as an end-user.
• [WEBARCH] defines URI ownership as "a relationship between a URI and a social entity [that] gives the relevant social entity certain rights, including [A] to pass on ownership of some or all owned URIs to another owner—delegation; and [B] to associate a resource with an owned URI—URI allocation."

Suggestions:

• Remove redundant 'person' from Protocol definition (persons are social entities).
• Distinguish resource ownership, storage ownership and URI ownership.

[woutermont]

Access mode

• [WAC]: An access mode is a class of operations that can be performed on one or more resources.
• [ACP] explicitly does not define specific Access Modes: Instead, any Access Mode granted is an instance of the Access Mode class. Access Modes and their granularity can be tailored to the needs of an application.
• [SAI] defines an access mode as as something that denotes operations (e.g. read, write) that a given authorization subject can perform on a resource.
• [SOLID-PROTOCOL] specifies the concrete operations 'read' (information about a resource’s existence or its description can be known), 'write' (information about resources can be created or removed) and 'append' (information can be added but not removed).

Suggestions:

• Align definitions; the one of [WAC] seems to sum it up pretty well.
• Add the aligned definition to Protocol.
• Remove definitions from [WAC] and [SAI] and instead borrow from and refer to Protocol.
• While there are probably arguments to be made why 'read', 'write' and 'append' deserve special attention, I feel this selection is still quite arbitrary, given the multitude of services that maybe provided over a resource, each with their own specific (combination of) effects. It might make more sense to define terminology to talk about services in general, rather than treat some (classes of) operations as special.

[woutermont]

ACL resource

• [WAC]: An ACL resource is represented by an RDF document [RDF11-CONCEPTS] that includes Authorizations determining access to resources.
• [ACP] Instances of the Access Control Resource (ACR) class connect resources to their Access Controls. (Instances of the Access Control class connect Access Control Resources to their Policies.)
• [SAI]: An acl resource as defined by [WAC] may be directly associated with a resource or indirectly associated with a resource through inheritance. It determines which authorization subjects can access a resource, and the modes of access they have for it.

Suggestions:

• Align definitions; for example: An access control resource (ACR) is a resource that contains the access control logic of one or more associated resources, of which it directly or indirectly determines which agents can access those resources and under which access modes.
• Add aligned definition to Protocol.
• Remove definition SAI, and instead borrow from and refer to Protocol.
• WAC and ACP both narrow down the concept. Let them refer to Protocol but still specify their extra constraints.

[woutermont]

WebID

• [SOLID-OIDC]: A WebID is a URI with an HTTP or HTTPS scheme which denotes an Agent (Person, Organization, Group, Device, etc.).
• [SAI]: A WebID is a web resource at an HTTP URI which refers to an agent. An identity profile document can be accessed by dereferencing the WebID. [WEBID]

Suggestions:

• WebID is defined in the WebID spec. Simply borrow the term from there and refer to it.

[elf-pavlik]

I think we should look at the same time at the dependencies graph. I captured the current one which most likely needs to be adjusted

• Normative References - normal line
• Informative References - dotted line

graph TD
  SOLID-PROTOCOL --> WEBID & ACP & WAC & SOLID-OIDC & SOLID-NOTIFICATIONS
  WAC --> WEBID
  WAC -.-> SOLID-PROTOCOL
  SOLID-OIDC --> WEBID & SOLID-PROTOCOL & UMA
  SOLID-NOTIFICATIONS --> SOLID-PROTOCOL
  SAI --> WAC
  SAI -.-> SOLID-OIDC
  SAI -.-> WEBID
  

Loading

A few things that stand out right away

• We have a lot of circular dependencies with SOLID-PROTOCOL, I think we should avoid it for Normative References
  • SOLID-OIDC should change to Informative Reference for SOLID-PROTOCOL
• ACP might need dependency on WEBID
• SAI doesn't really depend on WAC just the access modes, there is an issue for universal access modes Universal Access Modes API authorization-panel#194 and a related one to map them to protocol operations Ideas for access modes and corresponding operations in the Protocol authorization-panel#253
• SOLID-PROTOCOL seems very asymmetric, a big part of it defines Solid Storage and the rest requires other solid specs, extracting SOLID-STORAGE as a separate spec with fewer dependencies would make things more balanced.
• SOLID-OIDC is the only spec with mention of the Authorization Server (UMA), I think AS should be defined in SOLID-PROTOCOL

[woutermont]

Big +1 on mentioning the general structure of components (including AS) in the protocol. It might also be a good idea to include such a dependency graph there.

Small +1 on extracting the storage part to a separate document. Protocol can then normatively require all parts, while specific documents can also normatively rely on the storage spec without forming circular references.

Based on the discussions we were having around service descriptions, @elf-pavlik, those issues around generalizing access modes seem a good thing to revive. I'll look into that.

[jeff-zucker]

This script provides an up to the minute summary of all terminology definitions labeled by RDFa in the specs. Might come in handy for comparisons. It works by first scraping the listing of specs live from solidproject.org/TR/, then loads each spec and gets definitions from each based on RDFa.

[csarven]

At https://solidproject.org/TR/

1. Click on the dokieli menu (top-right)
2. Check the "Concepts" checkbox on the opened left pane/window. This will insert the "Include concepts" button (from 30 external references) into the document.
3. Click the "Include concepts" button. This will insert all concepts available from referenced documents (work items / specifications) - ordered by Specification, including Concept Schemes, Concepts, Collections
4. Bonus: Click "View graph". Inserts a graph of the Concepts/ConceptSchemes/Collections
5. Bonus Bonus: If you are signed in, click "Save As" and enter URL, e.g., https://example.org/foo . Saving to NSS / solidcommunity.net works best atm (dokieli is using the earlier OIDC authn)
6. ?
7. Profit.

(Can do the above from other specifications including SKOS, e.g., https://solidproject.org/ED/protocol )

Screenshots (of the above steps)

[csarven]

May have mentioned this (in a meeting?) already but I think this discussion is a good exercise towards #480

[TallTed]

"GitHub Discussions" really aren't; they're Q&As. You've got multiple issues here, each masquerading as an "answer" to the top-post "question". Some of those "answers" have comments; most don't, but could use them. I suggest creating an upper level issue of checkboxes, each corresponding to a secondary issue which is started with one of the above "answers" (really, questions), where discussion can proceed as is customary. As each thread reaches a conclusion, that can drive one or more PRs, and when those are merged, the checkbox can be ticked.