feat: initialise Solid26 implementors guide

[jeswr]

This is the beginning of the implementors guide discussed in #773 - currently it just fixes the specs and versions to be included.

Additional specs such as #774 (which I acknowledge I still owe a response to) may be added to this guide if developed and CG endorsed in time.

A preview link can be found here.

EDIT since there is a lot of active editing on this PR -- I am marking comments as resolved as I implement changes to ease navigation (cc @csarven @elf-pavlik - I hope this is ok, as far as I understand anyone with read access can still expand and read the content as they desire).

[jeswr]

@elf-pavlik I am comfortable working in this PR for now, and directly pushing changes in response to comments. I will keep using small well-described commits so that the lineage of changes is easy to follow.

@csarven I greatly appreciate the feedback, the majority I agree with and have implemented. The only thing I have not changed based on feedback is the leaving out of N3 Patch -- I respond to this below.

I also have one question -- from the feedback I am unclear on whether to use (CG-Draft, VERSION) or (ED, VERSION) when referring to most pieces of the spec. In the pushed changes I have used CG-Draft everywhere. Could you please advise on whether this is correct.

I don't understand why N3 Patch is being left out? Based on what CG consensus is this being recommended here?

The rationale for leaving it out is as follows:

1. Several known implementations of the Solid Protocol specification do not implement N3 Patch. This goes against the goal of "Solid26 collect[ing] the most mature and widely implemented specification versions."
2. It is unlikely that Notation3 will be chartered for a WG and put on REC track -- as no one seems to be driving this work at present. This means it would be hard for a Working Group, such as LWS, to produce a recommendation containing N3 Patch.
3. The Syntax and Semantics of Notation3 being ill defined and/or evolving last time I worked with it. Implementations such as EYE went back and forth on topics such as blank node scoping. In turn, my understanding is that N3 Patch is ill defined. As an aside, in writing this response I also came back across Reevaluating N3 Patch vs. SPARQL Update in the Solid Protocol #715, noting that RDF 1.2 is under way, I opened up Indicate DELETE misses w3c/sparql-protocol#42 (comment)

There is not currently consensus on this, I propose making this a topic of the next CG call. If there is more to discuss on N3 patch asyncronously, now may be an appropriate point to open a separate issue. So that we can have that discussion in a focussed thread.

[elf-pavlik]

In https://github.com/solid/solid26/blob/main/content.md#whats-included

The collection will clearly signpost where there may be breaking changes in future versions, so developers can plan accordingly.

https://github.com/solid/solid26/blob/main/content.md#relationship-to-linked-web-storage

The Linked Web Storage (LWS) W3C Working Group is currently developing a W3C specification with the Solid specification as one of its input documents. LWS is expected to define a subset of Solid's functionality as a formal W3C standard. Future Solid releases will align with and extend the LWS specification as it matures.

I think there are already a lot of expected changes that we can signal. I'm not sure if this should go into this PR.
On the other hand if this PR taks 2 more weeks it will be hard to do any other PRs afterwards.

[csarven]

@jeswr ,

Thanks for taking the feedback into consideration. Reminder re updating the references.

I also have one question -- from the feedback I am unclear on whether to use (CG-Draft, VERSION) or (ED, VERSION) when referring to most pieces of the spec. In the pushed changes I have used CG-Draft everywhere. Could you please advise on whether this is correct.

I think for solid26, it should use CG-DRAFT/FINAL because those are about as "stable" as it gets, and their timestamped snapshots are immutable references where one can ensure some precision on interoperability expectations. Take ED as WIP and subject to change. That said, EDs in the Solid CG for the most received enough support that their TR snapshots were fairly close to it (which IMO is a good thing).

I think the way you have the Notes right now are good, giving concrete heads-up or waypoint but leaving it at that. (Remove the "Editor's" bit from the Note).

Several known implementations of the Solid Protocol specification do not implement N3 Patch.

I can go along with anecdotal evidence for the sake of moving the discussion but it'd be appropriate to back this with some data even if it is incomplete. Which servers? Can you link to them? Did they provide implementation experience that's publicly accessible?

Could we compile a list of servers to see which features they support with regards to patching, and if and how that's compatible with Solid Protocol?

It is unlikely that Notation3 will be chartered for a WG and put on REC track

Ack. But then again the Solid CG is not running on WG timeline. It is incubation space. It can virtually reference / lean on any open standard.

The other concern about removing N3 Patch is that, then there is currently no patching recommended, not even SPARQL Update. I suggest to not dismiss N3 Patch in solid26. While if SPARQL Update can be updated is a worthwhile effort, there is no guarantee that it will happen or even in a timely matter. If pursuing N3 (Patch) is challenged, then SPARQL Update would be ass well. If implementations take up N3 Patch, then that's valuable feedback towards standards development - what more can be asked for than open source implementations giving input that "yes this is or isn't worthwhile, it worked or didn't or found it buggy or have security/privacy concerns or no we don't want to implement this because we have other opinions or options... we did most of it but wilfully violated this and that part because..." That's strong input to N3 / RDF development as well as Solid.

(Aside: I don't have a horse in this patching "race". dokieli implemented both as far as client-side matters go, and switched as the Solid Protocol evolved. Provided implementation feedback e.g., at #711 (review) and #652 (comment) ). I find N3 Patch and SPARQL Update both equally attractive in different ways. )

[jeswr]

Reminder re updating the references.

Which references are you referring to -- I believe the WAC ones are correctly updated to the snapshot version?

use CG-DRAFT/FINAL

👍 - done!

Remove the "Editor's" bit from the Note

👍 - done!

Could we compile a list of servers to see which features they support with regards to patching, and if and how that's compatible with Solid Protocol?

Good call. I suggest we leave it to the end of the week before going out for data collection in case any other features crop up that we want to ask about at the same time (given we have already asked for data on WAC/ACP implementations -- I don't want to be contacting implementors 3-4 times if we want data on more features).

The other concern about removing N3 Patch is that, then there is currently no patching recommended, not even SPARQL Update.

Yes, that was intended behavior. Happy to discuss this in the CG call tomorrow.

[jeswr]

In https://github.com/solid/solid26/blob/main/content.md#whats-included

The collection will clearly signpost where there may be breaking changes in future versions, so developers can plan accordingly.

https://github.com/solid/solid26/blob/main/content.md#relationship-to-linked-web-storage

The Linked Web Storage (LWS) W3C Working Group is currently developing a W3C specification with the Solid specification as one of its input documents. LWS is expected to define a subset of Solid's functionality as a formal W3C standard. Future Solid releases will align with and extend the LWS specification as it matures.

I think there are already a lot of expected changes that we can signal. I'm not sure if this should go into this PR. On the other hand if this PR taks 2 more weeks it will be hard to do any other PRs afterwards.

@csarven's steer in feedback has caused this document to become strictly the spec snapshotting and implementation guide based on the snapshot. I think this is a good focus and the suggested signposting belongs in a separate document.

[elf-pavlik]

I think this is a good focus and the suggested signposting belongs in a separate document.

Fine with me, can we already start that separate document? Will Solid 26 manifest in just those two documents or there are going to be more of them?

[csarven]

Should solid26 recommend more items from https://solidproject.org/TR/ to give a fair representation of what is relatively widely implemented and deployed?

For instance, taking the data from https://jeff-zucker.github.io/solid-load-profile/ as one source of input, we can infer what's out there in the ecosystem and use that for the implementers guide. I'll let the group be the judge of how to make a cut (e.g., based on count or other criteria) for what's reasonably deployed. I think it is hard to argue against the fact that Solid WebID Profile and Solid Type Indexes are used out there. If solid26 doesn't suggest anything beyond a WebID, it downplays personalisation and the social aspect of Solid, and if anything, looks strange for the state of things in 2026.

If there is other concrete data on the ecosystem, let's have a look.

[csarven]

Reminder re updating the references.

Which references are you referring to

You know, the References, like:

[SOLID-OIDC]
SOLID-OIDC. Aaron Coburn; elf Pavlik; Dmitri Zagidulin. W3C Solid Community Group. 28 March 2022. Version 0.1.0. URL: https://solidproject.org/TR/2022/oidc-20220328

[SOLID-PROTOCOL]
Solid Protocol. Sarven Capadisli; Tim Berners-Lee; Kjetil Kjernsmo. W3C Solid Community Group. 12 May 2024. Draft Community Group Report, Version 0.11.0. URL: https://solidproject.org/TR/2024/protocol-20240512

[WAC]
Web Access Control. Sarven Capadisli. W3C Solid Community Group. 12 May 2024. Draft Community Group Report, Version 1.0.0. URL: https://solidproject.org/TR/2024/wac-20240512

---

By the way, in solid26 you have:

Solid-OIDC (CG-DRAFT/FINAL, v0.1.0) is included in the Solid26 release.

But TR/oidc is not a "CG-DRAFT/FINAL" (nor can it be both). The latest published version is the one I referenced above: TR/2022/oidc-20220328. CG-DRAFT is only incorporated into its ED: https://solid.github.io/solid-oidc/ . An immutable snapshot version of that should be created at TR/{yyyy}/oidc-{yyyymmdd} and TR/oidc updated.

And if that new version is used for solid26, also update the editors of Solid-OIDC reference in solid26 accordingly since there is a change in the ED (after the TR/2022/oidc-20220328 release).

---

Use "CG-DRAFT" instead of "CG-DRAFT/CG-FINAL" in:

Web Access Control (CG-DRAFT/FINAL, 2024-05-12) is included in this release.

[csarven]

There should be a general recommendation that latest published versions of specifications should be used. That could be expressed along the lines of: at the time of this publication we recommend x but implementers are strongly encouraged to use latest published when available, and if you like to live on the bleeding edge, use the editor's draft.

On that last note, solid26 should also take the opportunity to thank implementers (somewhere upfront like in the Introduction) for helping to improve the Solid ecosystem, and any feedback on their implementation experience in meetings, issues etc., would be most appreciated.