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).

[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]

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.

[uvdsl]

Comments based on my understanding from the meeting on 2026-04-15.

[uvdsl]

Besides, the statement that there are clients that are not 100% conformant does not really provide guidance, i.e., is not really something an implementer can act on.

[uvdsl]

Suggested change

	<p>Work in progress: the content from the <a href="https://docs.google.com/document/d/1da2J-NsU3K-4kWEFOvhzIdrvy_KftewXdlxfu401kY0/edit?tab=t.j8ef1ds1wza#heading=h.r94tmffvqx0e">WebID guidance document</a> is to be integrated into this section.</p>

[uvdsl]

I'll update this section once I have the draft for "State of Solid-OIDC 2026" (or however might be called), see github.com/solid/solid-oidc/issues/250

[csarven]

Indeed the CG consensus is to recommend WAC based on data. Moreover, if "clients often" can be acknowledged based on data, one can acknowledge that "most servers and clients support WAC" based on data.

The Solid ecosystem is already aligned on WAC. If solid26 serves anything, it needs to acknowledge that reality so that it accomplishes the following:

• Implementations already supporting WAC have nothing to do because they are aligned with the rest of the ecosystem.
• Implementations only supporting ACP should support WAC so that they are aligned with the rest of the ecosystem. They can optionally drop ACP.
• New implementations are encouraged to support WAC so that they are aligned with the rest of the ecosystem.

That is quite literally what's useful here for readers. And I'd like to see the guideline along those lines.

[csarven]

I don't buy into the criteria to only include what is recommended by other drafts. Even when we entertain that idea of a criteria, it is evidently not applied consistently since there are "random" suggestions being made into solid26 that are neither grounded on actual specifications, data, let alone CG consensus. So, I suggest taking a moment and reflecting on that.

One of the key goals of solid26 is to encourage implementations to improve the ecosystem based on the entirety of CG's output: https://solidproject.org/TR/ . Where we have data, we make use of it to the best of our abilities, and where we don't, we try to make some educated guesses or at the very least make non-overly controversial suggestions without venturing off into personal opinions, and certainly not undermine existing efforts or mischaracterising them.

Solid WebID Profile is used in the ecosystem. It is also a fair representation of what is implemented out there. It may not be "perfect" but that is no different than any other specification in the Solid CG or anywhere else for that matter. Repeatedly diminishing it to nothing despite the data (as referenced numerous times now) indicating its substantial use is a disservice to the CG as well as a disruption in this workspace. Please stop doing that immediately!

[csarven]

I worry about all of this, and not because I necessarily agree/disagree with its contents. I don't question is usefulness either. It is just that it is too much in the weeds of trying to figure out what should be recommended. We've spent a lot of time on discussing most of what's written above, and what we came to was more or less what's in the Solid Protocol right now.

So, unless all of this that's written here is building on or drawing from 1) existing discussions, or 2) very rough consensus, or 3) based on implementation feedback, I suggest to not venture too far in this guide. It shouldn't repeat what existing specifications say. It should serve as a pointer or what the implementers may want to look up. "If you want to do accomplish this particular thing, then this and that will be handy to consider / do..." .

Here is an excellent example of what works as a guide on the subject matter:

Editing the Web - Detecting the Lost Update Problem Using Unreserved Checkout

"Saving a Document Not Known to Exist, Saving a Document Known to Exist, Handling Conflicts..."

I think referring to material like that is useful to implementers.

(In dokieli, to detect changes, we've followed those guidelines some of the base functionality for offline support: dokieli/dokieli#456 )

[uvdsl]

I can see where you are coming from. This is somewhat related with my concern on recommending something to Clients that they might not be able to use - which is addressed by the first paragraph (if etags are there, use them). I would prefer to keep the first paragraph.

On the particular flow spelled out here, I am a bit torn: On one hand, it does provide technical guidance. On the other hand, spelling this out bloats the bullet point a bit. Maybe a reference to [RFC9110 - Validator Fields] would suffice here to keep the granularity across the bullet points consistent, @jeswr?

[elf-pavlik]

This guide should include some basic security & privacy considerations. For example that WAC has no reliable way to authorize applications (assuming PR for conditions doesn't land) and ACP has only limited way of doing it for one's own resources as demonstrated in https://youtu.be/5Q1nUmGdaXE

I think it is better to clearly communicate about known limitations up front. Otherwise people may realize it somewhere down the road and fairly find it disappointing that this information wasn't disclosed.

[TallTed]

Lines 333 & 334 here are now on lines 341 & 342. Delete these existing 333 & 334.

Suggested change

	<ul>
	<li>

[uvdsl]

I believe (and I might be wrong here) that those elements (former L333-L334, now L360-L361) belong to the outer list whereas the mentioned L341-L342 (now L368-L369) belong to the inner list structuring the "etag flow". Did I catch that right?