Conversation
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
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? |
|
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. |
This comment was marked as resolved.
This comment was marked as resolved.
|
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. |
Co-authored-by: Tobias Käfer <6708974+kaefer3000@users.noreply.github.com>
* feat: boostrap webid section * feat: enhance Solid26 guidance sections * fix section headings * feat: enhance WebID Profile guidance with additional validation notes and refined predicate listings * feat: update WebID Profile note to include empirical data source for predicate usage * feat: add clarification on non-public WebID Document retrieval in WebID Profile * minor editorial * chore: consistency of term "Implementors Guide" with main PR Co-authored-by: Christoph Braun <braun@kit.edu> * fix foaf predicate and note on solid:oidcIssuer * Update solid26.html Co-authored-by: Christoph Braun <christoph.braun@protonmail.com> * Add Linked Data Notifications inbox reference to WebID Profile * Update WebID Document union process to mention ldp:inbox in discovery predicates * remove use case specificity on authenticated webid Co-authored-by: Christoph Braun <christoph.braun@protonmail.com> * Remove non-normative reference to Solid WebID Profile in comments * Update solid26.html Co-authored-by: Christoph Braun <christoph.braun@protonmail.com> * chore: remove mention of profile shapes Co-authored-by: Christoph Braun <christoph.braun@protonmail.com> * Tighten WebID term definitions in §3.1 Use "HTTP URI" for the WebID definition to match the normative section. Drop "Web resource" (not an established term) and the "Generally public / permissioned" hedging; state the auth property precisely where it matters. * Bound Extended Profile Document traversal in assembly algorithm Replace "transitively from the Preferences Document" recursion with an explicit, bounded traversal: one level from Extended Profile Documents linked directly off the WebID Document; no further traversal from Preferences-linked or Type-Index-linked documents. Introduce "discovery links" as a shorthand for rdfs:seeAlso / foaf:isPrimaryTopicOf / owl:sameAs and reuse it throughout §3.1.2 and §3.1.3. Add a note explaining why one level of traversal is needed when the WebID Document is not itself in Solid storage. * Drop 'publicly readable' qualifier in assembly step 1 Visibility of the WebID Document is covered in §3.1.2. Step 1 only needs to surface an error when retrieval fails. * Recommend an editable Extended Profile Document when WebID is not in Solid storage Address the case where the WebID Document itself cannot be modified by Solid clients: advise linking an Extended Profile Document in a Solid storage so clients have a writable attachment point for profile statements. * Require both text/turtle and application/ld+json for WebID Profile Document Align with Solid WebID Profile §3.1 Reading Profile, which extends WebID 1.0's Turtle-only requirement to include JSON-LD. * Refresh profile-editor list: drop PodBrowser, add dokieli PodBrowser is no longer actively maintained; dokieli is a widely-used reader/writer of agent profiles. * Clarify the predicate list ordering is advisory Make the reader/writer contract explicit: readers should accept any of the listed predicates as equivalent for a given field; writers typically commit to one. The stated order is a suggested preference and may vary by the ecosystem an application integrates with. * Drop unused [BIO] reference [BIO] was listed in §References but never cited in the document. * Surface error when WebID lacks solid:oidcIssuer A WebID without an oidcIssuer cannot authenticate via Solid-OIDC; clients should tell the user rather than failing opaquely further into the login flow. * Call out that missing Preferences/Type Index documents are not errors Not all WebIDs link a Preferences Document or Type Index documents; clients should skip their fetch silently rather than fail. * Use 'set union' in WebID Profile definition and assembly algorithm * Replace document-level self-describing filter with spec-aligned statement filter The earlier document-level 'self-describing' filter was a solid26-specific precaution not present in Solid WebID Profile. The current spec (§2 Discovery) states the profile is assembled by collecting statements with the WebID as subject or object. Drop the document-level filter; keep the statement-level filter and reword step 6 positively to match the spec. Also collapses §3.1.2 from two caveats to one (solid:oidcIssuer origin) and removes the now-obsolete step 4 in §3.1.3 — which means the 'switch steps 3 and 4' and 'explain step 4 better' colleague asks dissolve naturally. * Note the range of data-discovery mechanisms beyond the profile Client-side data discovery varies across the ecosystem; list the common mechanisms (Type Indexes, SAI, SPARQL / Quad Pattern Fragments endpoints, fixed paths under storage root, DCAT) without prescribing one. * Add §3.1.4 Security Considerations for solid:oidcIssuer protection Solid WebID Profile §Protected properties requires servers to protect solid:oidcIssuer triples, but no known Solid server implements this at time of publication; flag the implication for implementers in an informational subsection. * Remove references to WebID Profile SHACL shapes Drop the shape-validation note in §3.1.3, the profile-shapes.ttl reference and dagger markers in §4, and the companion 'not in the shape' annotation. Shape documentation belongs in the WebID Profile repo, not in this implementation guide. * Soften predicate-list framing to 'fallbacks to consider' Drop the SHOULD-accept-as-equivalent normative framing; present the list as optional fallbacks applications may consider. * Refresh predicate list from dokieli and SolidOS profile renderers Derive the fallback ordering from what dokieli and SolidOS profile-pane actually read: flip Name to foaf:name-first, broaden Avatar to the full dokieli chain, add social accounts, schema:hasOccupation, cco:skill, vcard:language, solid:preferredLanguage, schema:knows, vcard:url. Pull ActivityStreams and SIOC into the referenced vocabularies. * Drop section numbers from external spec references Per csarven (PR #781) and jeswr's agreement: section numbers in referenced specs are not reliable across snapshots. Keep link text as the section title only; internal cross-references within this document keep their numbers. * Language pass on §3.1 WebID: tighten prose, fix Implementors typo Remove duplicated and filler phrasing across §3.1: - Intro lists subsections (incl. new §3.1.4) without restating them. - Term-dl header: 'For the purposes of this section' dropped. - Fix 'Implementors Guide' typo in §3.1.1 heading. - Compact '?webid ?p ?o, where ?webid is the WebID and each ?iss is…' patterns to one statement-form with inline angle-bracket terms. - Drop '(e.g. a person)' filler. - Collapse 'MAY be hosted anywhere; it MAY, but need not, reside…' to single clause. - Tighten the Profile Document URI-resolution sentence, and several notes / algorithm steps that repeated 'Extended Profile Document' / 'Solid WebID Profile' within the same sentence. * Soften security-note framing and restore absent-link prose Use 'Not all Solid servers implement this protection' rather than 'No known Solid server', and restore the fuller wording about Preferences/Type Index documents being absent. * Replace numeric section refs with names; say 'set union of statements' Inline section names as link text instead of '§ 3.1.1' / '§ 3.1.3' style refs; reads naturally without relying on the TOC numbering. Both 'set union' occurrences now read 'set union of statements' to make the RDF-graph semantics explicit. * Drop the 'pinned specifications' framing Per csarven: framing certain specs as 'pinned' reads as gatekeeping and adds no value for the reader. Rephrase the §3.1 intro so requirements and common assumptions are stated as drawn from the Solid26 Implementation Guide specifications, and trim the §3.1.2 sub-bullet to 'These specifications do not preclude...'. * Extend WebID Profile definition to match algorithm sources The assembly algorithm unions statements from the Preferences Document and Type Index documents as well as Extended Profile Documents; the term definition now names all four sources. --------- Co-authored-by: Christoph Braun <christoph.braun@protonmail.com> Co-authored-by: Christoph Braun <braun@kit.edu>
Collect known security/privacy limitations across the pinned specs into a new top-level section with six subsections: - §5.1 WebID Profile Integrity (absorbs the former §3.1.4 on solid:oidcIssuer write-protection; adds WebID 1.0 §Security Considerations on profile-document integrity and the Solid-OIDC guidance that the RDF body is canonical for issuer discovery). - §5.2 Application Authorization (addresses @elf-pavlik #4276686814: WAC/ACP authorize agents not applications, Origin is not client identification, ACP Client-matcher limits). - §5.3 Access Control Leakage (WAC-documented leakage via Location, DELETE/PATCH status codes, lack of mandated audit trails). - §5.4 Personal Data in Access Control and Preferences (WAC PII transitive to acl:Control holders; Preferences Documents hold private data with protection delegated to WAC/ACP). - §5.5 Client Identity and Trust (Solid-OIDC §Out of Scope, §Client Secrets in browser SPAs). - §5.6 Profile and Storage Discoverability (Solid Protocol §Privacy Considerations; WebID 1.0 absence of privacy section). The new section explicitly notes it was drafted with generative-AI assistance to kickstart coverage and that community review is expected. Update §3.1 intro and TOC accordingly: §3.1.4 gone, new §5 + subsections added.
Done in |
Previous draft had six subsections and fifteen bullets that were overkill for the guide's scale. Collapse to a single flat list of the four points implementers most need to know: - WebID integrity (solid:oidcIssuer server protection) - Authorization authorizes agents, not applications - Consent transitivity in access control - Client identity / no-secrets-in-SPA Drop the WAC leakage subsection, Preferences delegation bullet, profile-discoverability subsection, and the header-vs-body spoofing footnote — these are real but niche, and their spec citations give implementers a pointer if they need them. TOC simplified accordingly: §5 has no subsection entries.
| </p> | ||
| <p> | ||
| Implementers of Clients are advised to consider whether their Client implementation should actually attempt to modify access rules at all: | ||
| An architectural separation between a Client executing application-specific logic and a Client executing authorization-related logic might be beneficial in terms of separation of concerns, maintainability, and re-usability of software components [<a href="#ref-authapp">BKY+24</a>]. |
There was a problem hiding this comment.
SAI Authorization Agent is another example. I have old demo where user can select resource in the app and get redirected to authorization agent to share access to that resource with other's in user's social graph.
There was a problem hiding this comment.
Another flow I want to implement would use access request and either
- redirect to authz manager if something like PAR https://www.rfc-editor.org/rfc/rfc9126.html is used
- send push notification to authz manager PWA and handle sharing user interaction this way.
There was a problem hiding this comment.
Omit : "Do not traverse further: discovery links in the documents fetched by this step, in extended profiles discovered from the Preferences Document, and in Type Index documents are not followed."
Add : Clients must descend two levels from the WebID document looking for extended profile links and may descend as far as they want. An author who places an extended document link in an extended document linked from the WebID profile should expect that second document to be read by clients. They can not count on links further away being discovered.
Note : I am not adamant about allowing extended document links in the type indexes and preferences file although I can think of many use cases for those. What I am adamant about is the ability to go at least two levels from the WebID document for extended documents other than the Preferences and Type Indexes.
| <ol> | ||
| <li><code>GET</code> the WebID Document. If it cannot be retrieved, surface a clear error.</li> | ||
| <li><code>GET</code> each linked document: Extended Profile Documents via <a href="#dfn-discovery-links">discovery links</a>, the Preferences Document via <code>pim:preferencesFile</code>, and Type Index documents via <code>solid:publicTypeIndex</code>/<code>solid:privateTypeIndex</code>. On <code>401</code>/<code>403</code> with a logged-in user, retry authenticated; Preferences and the private Type Index normally require authentication [<cite><a class="bibref" href="#ref-webid-profile">Solid WebID Profile</a></cite> § <a href="https://solid.github.io/webid-profile/#discovery">Discovery</a>, § <a href="https://solid.github.io/webid-profile/#private-preferences">Private Preferences</a>]. If the WebID Document does not link a Preferences Document or Type Index documents, those fetches are skipped; their absence is not an error.</li> | ||
| <li>For each Extended Profile Document linked directly from the WebID Document, fetch the Extended Profile Documents it links via its <a href="#dfn-discovery-links">discovery links</a>. Do not traverse further: discovery links in the documents fetched by this step, in extended profiles discovered from the Preferences Document, and in Type Index documents are not followed. Use cycle detection so no document is fetched twice.</li> |
There was a problem hiding this comment.
Line 574 directly contradicts line 565 and line 581 and introduces a much too restrictive set of bounds. The minimum set of bounds is, in my opinion, 2 traversals. This mandates nothing about the writability of any document, only that if there are links in an extended doc to other extended docs we should be expected to follow them at least one level, i.e. two levels from the WebID Document.
Here are two examples of what a limit of one link would prevent
<WebID1> rdfs:seeAlso <friendsAndFamily.ttl> .
<friendsAndFamily.ttl> rdfs:seeAlso <familyOnly.ttl> .
When permissioned accordingly, this pattern allows family to see the more general friendsAndFamily data and also the more specific family data, i.e. inheritance. Why would we want to prevent that kind of security structure?
Also prevented by a limit of one
<WebID1> owl:sameAs <WebID2> .
<WebID2> rdfs:seeAlso <myCV.ttl> .
With a limit of one, a discovery of WebID1 will not turn up myCV.ttl.
A limit of one greatly limits the freedom of users to partition and control their data.
This limit is in contradiction to the WebID Profile Draft and the drafts which preceded it and is being introduced at the last minute. Either drop the limit entirely or make it two levels.
|
|
||
| <div class="note"> | ||
| <h4><span>Note</span></h4> | ||
| <p>When the WebID Document is not hosted in Solid storage, clients cannot add new <a href="#dfn-discovery-links">discovery links</a> to it. The one level of traversal from Extended Profile Documents in Solid storage lets a client attach further Extended Profile Documents (for example, at different access levels) via links it can write.</p> |
There was a problem hiding this comment.
This introduces a completely unnecessary split between types of servers, requiring clients to follow differing expectations. It adds complexity to discovery. It allows the Identity server's decision on storing the WebID to control the ability for discovery on the Resource server and takes capabilities away from WebID owners. Why should we have to tell clients "If you're on server A, do B, but if you're on server C, do D?
There was a problem hiding this comment.
Also, this completely contradicts line 574.
The one level of traversal from Extended Profile Documents in Solid storage lets a client attach further Extended Profile Documents (for example, at different access levels) via links it can write.
No, if clients are only expected to descend one level from the WebID Document this advice is useless since clients will never follow those links.
Apply the three suggestion comments on PR #776: - Line 501: '(e.g. #me)' -> '(e.g., #me)' - Line 530: '(i.e. an unauthenticated...)' -> '(i.e., an unauthenticated...)' - Line 565: '(e.g. pim:storage...)' -> '(e.g., pim:storage...)' Co-authored-by: Ted Thibodeau Jr <tthibodeau@openlinksw.com>
Per discussion on PR #776: defer to the Security and Privacy Considerations sections of the relevant sub-specifications rather than restate them here. Removes §5 entirely along with its TOC entry and the §3.1 cross-reference. Solid-OIDC third-party-issuer concerns raised by @csarven and the additional point about issuer-trust requirements regardless of issuer scale are being taken upstream to the Solid-OIDC spec.
11 participants
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).