Comment on proposed specification document structure

[RubenVerborgh]

No description provided.

[justinwb]

Awesome start @RubenVerborgh!!! 👍 👍

Some quick thoughts after making a (very cursory) first pass:

• Where does data model for interoperability fit? I could see this being a candidate for a separate specification. I do see Data Shape Guidance as a place holder, but to me the combination of shapes, footprints, and discovery mechanisms that facilitates app interoperability should be a first class topic (even if it then points to a separate specification).
• Would server side data shape validation also fall under Data Shape Guidance?
• Should WebID be under a parent Identity section? Still put WebID as the only item and marked as MUST support, but with the idea being that if we want to add DID later, we insert it there beside WebID. This might be a good distinction to put in now, so that implementors consider modularity in their identity scheme up front.
• Should the title be "Solid Specification" instead of "Solid Ecosystem"? When I think of Ecosystem, I think of a combination of servers, people, applications, services, etc. Specification (imo) is more definitive.

[RubenVerborgh]

Thanks @justinwb 🙂

Where does data model for interoperability fit? I could see this being a candidate for a separate specification.

That was a terrible omission.
Now pointing to SHACL (maybe ShEx at some point) and to a new Footprints document.

Did not yet create a Forms document as I feel that will be less mandatory, but I expect that to be created at some point.

I do see Data Shape Guidance as a place holder

Indeed; that section was intended as non-normative advice about what shapes/ontologies to use in the short term.

• Would server side data shape validation also fall under Data Shape Guidance?

Likely not; that would probably a normative section.
Might become part of WAC.

Should WebID be under a parent Identity section?

Unsure and no strong opinion either way.

The idea was to give every yet-do-be-spec'ed technology its own section.
WebID-OIDC and WebID-TLS fit that definition—and so did WebID itself.
However, we thought that the WebID spec itself would be so short, that a document would be too much. We can still change.

Still put WebID as the only item and marked as MUST support, but with the idea being that if we want to add DID later, we insert it there beside WebID.

I would think that DID would just be a way to do WebID.

Currently, WebID is compatible with HTTP URLs. (But WebID ≠ HTTP URL.)
I'd expect then that WebID becomes additionally compatible with (some) DIDs.

In other words, I see WebID as a name for "an identifier that leads to a document about you in RDF", regardless of whether that identifier is a URL or a DID.

Should the title be "Solid Specification" instead of "Solid Ecosystem"? When I think of Ecosystem, I think of a combination of servers, people, applications, services, etc.

No strong opinion, just my two cents:

• I chose another word because "the specification" might be misleading, as there are multiple.
• I actually like the notion of that combination; I think it fits.

[acoburn]

I am strongly supportive of the proposed structure. 👍

I do have a few minor comments. Since there is no text (yet) in the relevant sections, this is rather tentative feedback.

1. In section 2 (Authenticated Resource Access), both WebID-OIDC and WebID-TLS are listed at the MUST and MAY conformance levels, respectively. This makes sense when the resource server is also an identity provider (as is the case with NSS and Inrupt-PodServer). But this assumption may not always hold; in fact, it is not an uncommon pattern to separate the resource server from the identity provider. Given such a decoupled structure, do these conformance requirements make sense? That is, by "Pod Server" do we mean IdP + ResourceServer? Can we talk meaningfully about a conforming resource server that doesn't have an embedded IdP?

2. Related to point 1, above, should there be a separate "Identity Management" section, distinct from the current "Authenticated Resource Access"? The two are clearly related, but it might be useful to draw some distinctions in the specification.

3. And (very, very minor) should section 2 be titled "Authenticated Resource Access and Management" or even simply "Authenticated Resource Management"? Access is certainly very important, but LDP provides a whole system for resource management that I don't want to overlook. I am also completely fine with the current title, if you prefer that.

4. It would be nice to include a section with definitions. E.g. what is a "Solid client"? what is a "Solid data pod"? etc.

5. In addition to a "Security Considerations" section, many specifications include a "Privacy Considerations" section. Since user privacy is of significant interest to Solid, that might be a good section to add (or combine it with the Security Considerations section).

[RubenVerborgh]

Thanks, @acoburn!

• In section 2 (Authenticated Resource Access), both WebID-OIDC and WebID-TLS are listed at the MUST and MAY conformance levels, respectively. This makes sense when the resource server is also an identity provider (as is the case with NSS and Inrupt-PodServer).

Good point; however, this was meant from the perspective of access control, not as IDP.

But indeed, these things would need to be clarified as the text is written; they are just placeholders for now.

• Related to point 1, above, should there be a separate "Identity Management" section, distinct from the current "Authenticated Resource Access"?

Yes, indeed. I wonder whether that could also be seen as an optional part, cfr. the other specs listed at the end. Tracking in #7.

• And (very, very minor) should section 2 be titled "Authenticated Resource Access and Management" or even simply "Authenticated Resource Management"?

Good point; no strong opinion. Can be filled out as we go.

• It would be nice to include a section with definitions. E.g. what is a "Solid client"? what is a "Solid data pod"? etc.

Absolutely; added in c382725.

• In addition to a "Security Considerations" section, many specifications include a "Privacy Considerations" section. Since user privacy is of significant interest to Solid, that might be a good section to add (or combine it with the Security Considerations section).

Great point; added in 8d68c15.

[justinwb]

Now pointing to SHACL (maybe ShEx at some point) and to a new Footprints document.

I think there's a legitimate reason to include ShEx now along with SHACL. I don't think the two are mutually exclusive and have some different strengths / weaknesses when applied to different use cases.

• Would server side data shape validation also fall under Data Shape Guidance?

Likely not; that would probably a normative section.
Might become part of WAC.

Have to give this a bit more thought, but I really like the idea of incorporating server-side validation directives with WAC rules. It comes at the expense of making WAC a little bit more complex, but the fit seems natural to me 👍

The idea was to give every yet-do-be-spec'ed technology its own section.
WebID-OIDC and WebID-TLS fit that definition—and so did WebID itself.
However, we thought that the WebID spec itself would be so short, that a document would be too much. We can still change.

Are we picking up the WebID specification effort and incorporating it here? Since active work on the WebID spec outside of Solid seems to have tapered that might not be a bad idea.

In other words, I see WebID as a name for "an identifier that leads to a document about you in RDF", regardless of whether that identifier is a URL or a DID.

I think we're probably agreeing on the macro point - that the notion of identity should be fairly generic, with more than one option available as long as it gives you an identifier that leads to a document about you in RDF. I think the current WebID specification would need to be updated to address this generality though.

Should the title be "Solid Specification" instead of "Solid Ecosystem"? When I think of Ecosystem, I think of a combination of servers, people, applications, services, etc.

No strong opinion, just my two cents:

• I chose another word because "the specification" might be misleading, as there are multiple.
• I actually like the notion of that combination; I think it fits.

Fair point, especially when we're covering both server and client in one document. Is it right to combine all into one? I could see having a server, client, and data model spec. Not arguing for this just yet - but think it might be worth a discussion. I do realize we run the risk of too many specs flying around so that may be a legitimate reason not to.

[justinwb]

A few other items we may want to consider including. These are also things that I do think could go into a Standard Pod Data Model spec document if we decided to break out into one.

• User Preferences (e.g. Global, by Data Type, by App)
• App Registry
• Internationalization / Localization

[kjetilk]

I haven't had time to read your comments, I just wanted to note one thing that we forgot to discuss before I forget it again: URI Normalization. RFC3986 gives some guidelines, but it is hardly enough, as we already noticed with the http vs https debate that we had because of breakage with vocabs that were being loaded. It is also extremely important for components that do any kind of query that they agree on how to tell if to URIs refer to the same resource. Another field where it is important is with HTTP proxies, if one proxy has a different idea of a resource than the server behind it, it could lead to very strange bugs, even security failures if the proxy and the server doesn't agree on what ACL applies to which resource.

We cannot eliminate false negatives but we should minimize their impact by being strict when we can.

[kjetilk]

Where does data model for interoperability fit? I could see this being a candidate for a separate specification.

That was a terrible omission.

Oh, actually, we did have it up and dismissed it, don't you remember, @RubenVerborgh :-) The following is an elaboration of my opinion on it:

So, with this bunch of specs (pending decision on The Name), it would define the client-proxy-server interface, not the app-app interoperability. That should be a different matter.

How SHACL and/or ShEx is used may be specified, but other than that, I'm very much doubting that it makes sense to spec the various shapes, forms and footprints in any similar manner to these foundational documents at all.

Developers need to be free to augment and pillage to quickly meet their needs, and a spec is too rigid a structure for that. If they have to go and ask to add a predicate and have a process around having it accepted for their application to work, they are unlikely to develop on Solid, the interoperability has to be emergent, not mandated.

If you have a Task list that needs another field, then sure, go and add it, if your apps gets popular, or indeed to make your app popular, you need interoperability, and then, make sure it is in a shape that others can use. Preferably, that should all happen in-band if you ask me. It is a very different process than what is needed for the foundational specifications.

Since it is also a pretty clearly defined area, I think the whole problem complex should be separate.

[RubenVerborgh]

I'm very much doubting that it makes sense to spec the various shapes, forms and footprints in any similar manner to these foundational documents at all.

We did exclude spec'ing that indeed, I remember that discussion.

But the generic mechanisms of shapes and footprints can/should still be discussed, right?

[kjetilk]

But the generic mechanisms of shapes and footprints can/should still be discussed, right?

We should, but I think it might well happen in a different "Panel".

[RubenVerborgh]

True, but main spec should link to them?

[dmitrizagidulin]

👍 , this is great stuff!

[kjetilk]

True, but main spec should link to them?

Not sure... The way that I think about it is that "The Spec" is what you need to implement a certain artifact. A different artifact needs a different "The Spec", and an overview of "all specs" is a documentation thing, not a specs thing. So, the critical question is what the artifact is, and that's why I'm not completely sure.

[maxidorius]

As an outsider that has never contributed to the solid repos, but that has been following the project and is currently working on a server implementation, I want to say this initiative is very appreciated! A single overall document that would allow to get all the required knowledge and specification documents is much needed. At the moment, it's a lot of reverse engineering, but not yet successful into building something compliant with the node implementation.

One item which I don't see being covered, but also don't see a standalone document for, is how pods actually federate with each other, and how messages/requests are being authenticated - am I missing something?

[RubenVerborgh]

how pods actually federate with each other

In the sense of query? That would be https://solid.github.io/specification/#query

[maxidorius]

In the sense of query? That would be https://solid.github.io/specification/#query

I meant in general. Query is a specific call (if I understand this right), but I was more thinking in a general sense of "how does one pod send/write data to another pod, being the /inbox/ or any other path, in an authenticated way?"

The idea is really to know from which IRI the request is coming from. So per example, the pod https://john.example.org/profile/card#me would receive an HTTP request to /federate/write/ and would need to know that it is indeed https://alice.example.org/profile/card#me talking to it.

[RubenVerborgh]

"how does one pod send/write data to another pod, being the /inbox/ or any other path, in an authenticated way?"

Writing to other pods is general auth.

[maxidorius]

Writing to other pods is general auth.

I think that's exactly the thing that should be expanded on in this repository, to explain how such mechanisms work at the Solid level. The document has section for "Clients and apps", and it could use a "Servers" section too. How servers are supposed to exchange data is non-obvious at the moment for someone who just picks up the spec.

[RubenVerborgh]

The document has section for "Clients and apps", and it could use a "Servers" section too.

It does; it's called “Authenticated Resource Access”. It's both a server and client matter though, since the interface exposed by a server is accessed by a client.

How servers are supposed to exchange data

The moment they write, they act as a client. This diagram might help clarify that: https://rubenverborgh.github.io/WebFundamentals/architecture/#client-server-relative

[csarven]

Really glad to see the high-level directional concerns and proposals as raised in https://lists.w3.org/Archives/Public/public-solid/2019May/0015.html made its way here. Personally, that's AWWW's Orthogonality, and relatively the bottom-up approach how the specs will come about.

I think the title along the lines of "ecosystem", "overview" or maybe even very loosely a "primer" fits for this document for now. We can decide on the exact terminology later once more things settle down.

Any non-normative content can stay in this document. I can't particularly think of how or why any normative can be in this document, and that all normative content most likely deserves its independent document which can be referred from this document. We also need to think of terms how each atom spec will continue down the line eg. if a W3C WG can adopt one of the specs under a Rec track - which would be an idea scenario for all specs mentioned in this document.

Re WebID-OIDC/MUST, WebID-TLS/MAY... this is meaningful and useful today, however subject to change down the line if WebID-Foo comes along. For example, will WebID-OIDC become MAY then or continue to be a MUST and thereby expecting all systems to have the know-how for both OIDC and Foo - increased complication while being backwards compatible. I think addressing #8 can shed light on how the ecosystem approaches the conformance levels for these mechanisms over time.

Re SHACL vs ShEx (or similar seemingly equivalent but different) specs.. we approach that based on use cases and requirements as a guide #9 , so, eg. to achieve x, use S. The Social Web Protocols does this nicely: https://www.w3.org/TR/social-web-protocols/ and doesn't dictate. Guides.

Will write more later..

[RubenVerborgh]

Saw no concerns specifically related to structure; feel free to open new issues for the points raised above.