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.

[elf-pavlik]

@langsamu @jeswr could validations be done with SHACL shapes and for valid cases transformation with reasoning over a set of N3 rules and/or SPARQL CONSTRUCT queries?

[uvdsl]

Hi all, I updated the document based on my understanding from the discussion of the CG meeting on 2026-04-15. Please suggest changes in-line, this update is just a suggestion to take baby steps towards something that we can all agree on. Thanks!

[elf-pavlik]

I think this is pretty good. As for access requests Solid/LWS is in a bit of a limbo so we there isn't that much clarity that could be offered. I still find it helpful to signal that there is a common trend of relying on specialized app/service to manage access policies. Solid Protocol currently having MUST on WAC and ACP for all clients is rather unfortunate, down the road there could be more specialized class of products which would be the requirement subject. For Solid 26 we can't do much better that having a hand-wavy explanations.

Given that this PR may still take some time.

• Add condition to authorization evaluation web-access-control-spec#134

I think it may be fair to mention that until that lands WAC doesn't have a reliable way to authorize applications and effectively they all run in sudo mode.

[csarven]

This doesn't particularly amount to more than plumbing. Whether a part of a client is using a dedicated library to do access control that's conforming to a specification is no different than a client that includes its own access control that's conforming. The premise that splitting is better is not due to specifications or its conformance but only amounts to good development practices (as you've mentioned above). At the end, it boils down to whether X is conforming to Y and whether Z trusts it. These are different matters than what the first may suggest to us.

So, I would rather see encouragement that is more about applications using access control implementations where their conformance is verified.

There should be a related point (perhaps elsewhere in this document) about clients using tested, trustable, or publicly verifiable implementations (open source tends to guarantee that possibility to a good degree).

[elf-pavlik]

I don't see it as plumbing. I don't intend to agree on it now or do data gathering, we can treat is as anecdotal. User may have only 1 dedicated client which has acl:Control permissions. All other clients would NOT have any acl:Control permissions at all and have no business in ever setting any Authorizations. Currently MUST on ACP and MUST on WAC assumes that all clients are required to set authorizations. IMO we need a class of products, which would be fully conformant without supporting anything that wouild ever require having any acl:Control access.

[uvdsl]

@csarven thank you for your feedback. I am not sure if I completely understand the implications that would have for the wording. Could you make an inline suggestion for wording such that I can better grasp the difference here? Thanks!

[csarven]

@uvdsl, The separation of concerns point can stay but it is separate. I think the key addition needed is about architectural separation advice is a software deveopment consideration, not a conformance requirement. Whatever wording is used, it should make clear that the spec's primary concern is that clients use conforming implementations that are independently verified, e.g., through open test suites and publicly documented implementation reports.

[csarven]

Ok, this point seems good. Not sure I understand what "custom Server functionality" means. My interpretation is that proprietary designs should be discouraged entirely. Did you mean something else or am I misreading?

[jeswr]

This is how I would read it - I would think functionality such as a server sending "share request" emails is ok.

Suggested change

	<li>processed by either a particular Client that is able and trusted to manage access controls (such as an access management or authorization application) or by custom Server functionality</li>
	<li>processed by either a particular Client that is able and trusted to manage access controls (such as an access management or authorization application) or by custom Server functionality (e.g. sending a "share request" email to the users email address for the user to accept).</li>

[uvdsl]

Hm. Fair point. I was thinking about "where" the request would be processed but as the user is the one to ultimately consent, processing on server side does not make much sense here... I shall remove that part.

@jeswr, good thinking about the email thing - I would rather see that as a notification or a means to transport the access request.

I agree that Solid26 should not venture into proprietary designs.

[uvdsl]

Suggested change

	<li>processed by either a particular Client that is able and trusted to manage access controls (such as an access management or authorization application) or by custom Server functionality</li>
	<li>processed by a particular Client that is able and trusted to manage access controls (such as an access management or authorization application)</li>

[csarven]

I think this needs a bit of a "therefore" or "so we encourage this and that and watch out for this and that" kind of a sentence at the end.

This section could also mention some fundamental things about what does Solid-OIDC entail when identity is ultimately is controlled by a third-party. Implementers should be warned about potential risks of multiple identities being used under the same origin - consider tying it to URI ownership (AWWW).

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

Yes, please add a section on Solid WebID Profile. It is pretty core.

[csarven]

The former is neither produced or controlled by the CG. The latter is a CG work item. Please remove reference to a Google doc (which is in and itself a non-starter but that's a separate discussion) and refer to an actual CG asset based on consensus.

[csarven]

#776 (comment)

[jeswr]

Suggested change

	<li>
	For WAC, the data shows 13 server-side implementations, deployment in 11 services, and 19 client-side implementations.
	WAC is considered the pragmatic, user-friendly, and extensible standard that effectively covers nearly all of the use cases from current Solid Apps.
	</li>
	<li>
	For ACP, the data shows 4 server-side implementations, deployment in 1 service, and 4 client-side implementations.
	ACP is considered as a highly powerful but complex tool that has not seen wide adoption in the community as the data indicates.
	<li>
	For WAC, the data shows 13 server-side implementations, deployment in 11 services, and 19 client-side implementations.
	WAC is pragmatic, user-friendly, and extensible. WAC has all the features that most open, social, Web applications need.
	</li>
	<li>
	For ACP, the data shows 4 server-side implementations, deployment in 1 service, and 4 client-side implementations.
	ACP is highly expressive. ACP is most commonly applied in enterprise and B2B applications of Solid involving complex permissions.

Trying to be more constructive by highlighting what the better use-case(s) for each language are.

[uvdsl]

Hm. Not happy here.

WAC has also been applied in "enterprise and B2B applications" (MANDAT and other German projects). WAC is also being used by W3C, Openlink, and potentially others iirc.

In this note, I prefer sticking to what the gathered data tells us. Other remarks might be better placed elsewhere.

Suggested change

	<li>
	For WAC, the data shows 13 server-side implementations, deployment in 11 services, and 19 client-side implementations.
	WAC is considered the pragmatic, user-friendly, and extensible standard that effectively covers nearly all of the use cases from current Solid Apps.
	</li>
	<li>
	For ACP, the data shows 4 server-side implementations, deployment in 1 service, and 4 client-side implementations.
	ACP is considered as a highly powerful but complex tool that has not seen wide adoption in the community as the data indicates.
	<li>
	For WAC, the data shows 13 server-side implementations, deployment in 11 services, and 19 client-side implementations.
	WAC is considered the pragmatic, user-friendly, and extensible standard that effectively covers nearly all of the use cases from current Solid Apps.
	</li>
	<li>
	For ACP, the data shows 4 server-side implementations, deployment in 1 service, and 4 client-side implementations.
	ACP is considered an expressive and complex alternative that might be chosen to satisfy corresponding use-case specific requirements.

[csarven]

This thread seems outdated. @uvdsl , could you resuggest/apply what you wrote above? I find @uvdsl 's suggestion appropriate/accurate.

[jeswr]

Suggested change

	Servers are strongly encouraged to implement Web Access Control (<a href="https://solidproject.org/TR/protocol#web-access-control">WAC</a>), see <a href="#web-access-control">below</a>.
	Clients often support only one <a href="https://solidproject.org/TR/protocol#authorization">authorization</a> specification.

My understanding of the last call is that we had agreed to be more neutral in this statement - and then provide the data from which people can draw their own conclusions. Further https://github.com/solid/specification/pull/776/changes#r3096832416 helps to identify where each language is used so that developers select the right language based on what their use for Solid is.

[uvdsl]

Hm, that does not match my understanding. My understanding is that WAC is still to be recommended, while it is acceptable to acknowledge existence of ACP based on the gathered data.

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

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

[timbl]

You suggest ACP implementations should switch to WAC . But that is mathematically impossible as ACP is a more expressive language, more powerful, as we discussed on the CG call of April 15. Those systems who found needed the extra power of ACP can't use WAC. The guide must mention both.

[jeff-zucker]

My $0.02 (or less) - Clients must support WAC; may support ACP with the understanding that ACP is experimental. Servers should support WAC and if they do not, they should do so with the understanding that most applications will not be able to access the resources where there is no overlap between WAC and ACP. Gives clients a clear direction, lets Servers experiment.

[EDIT: though I would see this as a temporary measure. Server implementers should be encouraged to put their energy into improving WAC and we should converge on it.]

[elf-pavlik]

I don't know any servers that support both ACP & WAC at the same time. In CSS one needs to choose one in the config but can't do both at the same time. Very likely it would be pretty hard for a server to support both at the same time and it would probably still require to choose only one for any given storage.
So if features provided only by ACP are required, argument to support WAC doesn't seem that helpful.
I don't think we can do much in a short timeline for Soild 28 we could take systematic approach, for example proposed in solid/authorization-panel#121 (comment)

[TallTed]

People who encounter "Solid Protocol 0.11" and "Solid26" are fairly likely to discard the former and treat the latter as if it's the authoritative document, no matter how many or strong disclaimers exist. It's taken me some time to stop mentally reading "Solid26" as "Solid version 26" or maybe "Solid version 2026". I don't have an immediate suggestion for what to change it to, but I sincerely hope someone else will have one or more to contribute, and even more that there is time before whatever deadline is talked about above as if every reader knows what it is (which I do not).

EDIT: I had a thought. "SolidSnapshot2026" or maybe "Solid_Snapshot_2026".

[elf-pavlik]

EDIT: I had a thought. "SolidSnapshot2026" or maybe "Solid_Snapshot_2026".

I tend to think of it as State of Solid 2026, which at some point could be more data driven like https://stateofjs.com

[jeswr]

Suggested change

	<p><a href="https://solidproject.org/TR/2024/wac-20240512">Web Access Control</a> (CG-DRAFT, v1.0.0, 2024-05-12) is included with the following comments:</p>
	<ul>
	<li>
	WAC is actively being maintained and developed: To officially extend WAC with functionality desired by the community, a corresponding proposal is seeking implementers' feedback (<a href="https://github.com/solid/web-access-control-spec/pull/134">solid/web-access-control-spec#134</a>).
	</li>
	</ul>
	</div>
	<p><a href="https://solidproject.org/TR/2024/wac-20240512">Web Access Control</a> (CG-DRAFT, v1.0.0, 2024-05-12) is included.
	</div>

Ideally we will generate many such proposed changes in the next few months in response to implementors feedback. Given this is the first of many, in-line feels the wrong place to highlight it.

Instead I suggest that we have a "living" section at the bottom of this document enumerating proposals with "Requests for Feedback" that are outside of the Solid 2026 guide / created in response to feedback on the guide.

When we reach a critical point of such requests - we could then move these to a different document or process.

[uvdsl]

Hm... wouldnt we then also move the comment on Solid-OIDC?
Open for discussion here... If we move the comments form the specs to a dedicated section, wouldnt it just make sense to have a table/list of all the specs instead of having distinct sections (which would be mirrored in the "living" section again?" Maybe the table of specs and versions is an idea worth considering regardless?

[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

	<li>processed by either a particular Client that is able and trusted to manage access controls (such as an access management or authorization application) or by custom Server functionality</li>
	<li>processed by a particular Client that is able and trusted to manage access controls (such as an access management or authorization application)</li>

[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

[uvdsl]

There was no agreement to add ACP as recommended by Solid26, at least to my understanding from the meeting on 2026-04-15.

Suggested change

<li class="tocline"><a class="tocxref" href="#access-control-policy"><bdi class="secno">2.4</bdi> <span>Access Control Policy</span></a></li>

[timbl]

My understanding of that meeting of 2026-04-15 was that there was an agreement to mention both WAC and ACP, also mentioning there are more server implementations of WAC than ACP. Disagree with the change above.

[uvdsl]

There was no agreement reached to include ACP as recommended here. ACP is indeed mentioned and acknowledged by Solid26 based on the summary of the gathered data, so this concern is already accounted for.

[csarven]

I meant the issue and the note.

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

[kaefer3000]

When reading the document, I was confused by the bullet point. The previous bullet points on servers and clients -to me- seem to concern a wide range of servers and clients. This bullet point however makes -at least in my understanding- a remark on such clients that want to modify access control. Such clients are more niche in my opinion. When keeping this bullet points, I would suggest to make this clear in the beginning of the bullet point such that those (and I guess most) readers know that they can skip this bullet point.

[TallTed]

Suggested change

	Solid26 selects for the most widely implemented specification versions at the time of this documents publication.
	Solid26 selects for the most widely implemented specification versions at the time of this document's publication.

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

[csarven]

Use this instead of base: <link href="https://www.w3.org/StyleSheets/TR/2021/cg-draft" media="all" rel="stylesheet" title="CG-DRAFT" />

[csarven]

This should use paragraph markup.

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