diff --git a/index.html b/index.html index 6c1baf22..ab9a88ad 100644 --- a/index.html +++ b/index.html @@ -118,6 +118,13 @@

Work Items

Current Stage + + + Solid26: Implementation Guide + https://github.com/solid/specification + CG-DRAFT + + Solid Protocol diff --git a/solid26.html b/solid26.html new file mode 100644 index 00000000..99a3d789 --- /dev/null +++ b/solid26.html @@ -0,0 +1,706 @@ + + + + + Solid26: Implementation Guide + + + + + + + + +
+
+
+

Solid26: Implementation Guide

+

Draft Community Group Report,

+
+ More details about this document +
+
This version
+
https://solidproject.org/TR/solid26
+
+
+
Latest published version
+
https://solidproject.org/TR/solid26
+
+
+
Editors
+
Jesse Wright (University of Oxford)
+
Christoph Braun (FZI Forschungszentrum Informatik)
+
+
+
Published
+
+
+
+
Modified
+
+
+
+
Feedback
+
GitHub solid/specification (pull requests, new issue, open issues)
+
+
+
Language
+
English
+
+
+
Document Type
+
Implementation Guide
+
+
+

Copyright © 2026 the Contributors to Solid26: Implementation Guide, under the W3C Community Contributor License Agreement (CLA). A human-readable summary is available.

+
+
+
+
+

Abstract

+
+

This document is an implementation guide for Solid26 — a snapshot of the most mature and widely implemented Solid specification versions, collected to help developers and organisations identify a common baseline. It provides practical guidance for implementing the Solid specifications included in this collection.

+
+
+
+

Status of This Document

+
+

This document was published by the W3C Solid Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups.

+

This document is intended to provide implementation guidance for the Solid specifications collected in the Solid26 release. The content of this guide is informative and non-normative. It may be updated, replaced, or obsoleted by other documents at any time.

+

Comments regarding this document are welcome. Please file issues on GitHub.

+
+
+ + +
+

Introduction

+
+

+ The Solid Technical Reports comprise multiple specification documents with differing levels of maturity. + The Solid Protocol bundles the specifications that, together, provide applications with secure and permissioned access to externally stored data in an interoperable way. + Solid26 points implementers to fixed versions of the Solid Protocol and its sub-specifications, a stable snapshot of the specifications to build against today. + Solid26 selects for the most widely implemented specification versions at the time of this document's publication. +

+

This document does not define new normative requirements, but rather identifies and collects the specifications needed to build interoperable Solid applications and servers.

+
+
+ +
+

Specifications

+
+

This Solid26 Implementation Guide recommends the following specification snapshots.

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
SpecificationVersionDetails
Solid Protocol(CG-DRAFT, v0.11.0, 2024-05-12)Link
Solid-OIDC(v0.1.0, 2022-03-28)Link
Web Access Control(CG-DRAFT, v1.0.0, 2024-05-12)Link
+ +
+

Solid Protocol

+
+

The Solid Protocol (CG-DRAFT, v0.11.0, 2024-05-12) is included with the following comments:

+
    +
  • +

    Clients might encounter Servers that do not support Modifying Resources Using N3 Patches despite it being required by the Solid Protocol. Clients can use Allow headers to determine if a Server supports HTTP PATCH requests.

    + +

    If a server does not support HTTP PATCH, a client can read-modify-write via GET then PUT. To avoid the lost-update problem [W3C — Editing the Web], issue the PUT conditionally with If-Match carrying the ETag returned from the GET; the server responds with 412 Precondition Failed if the resource has changed in the interim. If only Last-Modified is exposed, If-Unmodified-Since serves the same role, though its one-second resolution is coarser than ETag-based validation. See RFC 9110 § Validator Fields for the full mechanics.

    +
    • +
  • +

    + Servers are strongly encouraged to implement Web Access Control (WAC), see below. +

    +
    +

    Note

    +

    The March 2026 implementation survey yields the following results (archived):

    +
      +
    • + 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. +
      • +
    • + 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. +
      • +
    +

    The data shows that most clients implement only one access control language, despite the Solid Protocol requiring Clients to conform to both WAC and ACP.

    +
    +

    + In case WAC seems not to satisfy implementers' requirements, implementers are strongly encouraged to verify their understanding of the matter in community discussion by providing feedback to the community. + If WAC is not able to satisfy the requirements, implementers might consider ACP or other suitable mechanisms to achieve their goals. + Client implementers are advised to consider that their Client implementation will not be able to interoperate with every conforming Server their Client might encounter. +

    +
    • +
  • +

    + Some Clients might desire to update access control on particular resources, e.g., for sharing a user's data with another user or application. + In such a case, Clients are strongly encouraged to rely on or make use of conforming implementations that are independently tested and verified, e.g., through open test suites and publicly documented implementation reports. + Servers might only allow such tested and verified conformant Clients to modify access control rules. +

    +

    + 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 [BKY+24]. + Such separation allows Clients to rely on an externally tested and verified Client already implementing of authorization-related logic. + Such approach to modifying access control rules might rely on +

    +
      +
    • access requests to update access control rules accordingly on a Server
      • +
    • issued by the application-logic Client
      • +
    • processed by a particular Client that is able and trusted to manage access controls (such as an access management or authorization application)
      • +
    +
    • +
+
+
+ +
+

Solid-OIDC

+
+

Solid-OIDC (v0.1.0, 2022-03-28) is included with the following comments:

+
    +
  • +

    Despite Solid26 including Solid-OIDC v0.1.0, it is not widely implemented. In particular, the Solid-OIDC recommended flow of User-Managed Access (UMA) is not supported by any open source Solid Server implementation. Current implementations rely on the access token issued by the OpenID Provider of the user to authenticate the user at a Solid Storage.

    +
    • +
+
+

EDITORS' Note

+

+ A corresponding Group Note document that accurately reflects current implementations is being drafted by Christoph Braun. This PR is waiting for that document to be available and ready to reference before merging. +

+
+
+
+ +
+

Web Access Control

+
+

Web Access Control (CG-DRAFT, v1.0.0, 2024-05-12) is included.

+
+
+ +
+

WebID 1.0

+
+

WebID 1.0 (W3C Editor's Draft, 5 March 2014) is included.

+
+
+ +
+

Solid WebID Profile

+
+

The Solid WebID Profile (CG Draft Report, v1.0.0, 12 May 2024) is included with the following comments:

+ +
+
+ +
+
+ +
+

Implementation Guidance

+
+ +
+

WebID

+
+ +

This section gives WebID implementation guidance for the Solid26 Implementation Guide. It covers requirements and common assumptions drawn from the Solid26 Implementation Guide specifications, and a profile assembly algorithm. Client-side guidance is in a separate section; known limitations are collected in Security and Privacy Considerations.

+ +

Terms used in this section:

+
+
WebID
+
An HTTP URI that denotes an agent [WEBID], [SOLID-PROTOCOL].
+
WebID Profile Document
+
The document obtained by dereferencing a WebID.
+
Extended Profile Document
+
A further document linked from the WebID Profile Document that contains additional statements about the WebID; retrieval may require authentication.
+
Preferences Document
+
A document, linked from the agent's WebID Profile via pim:preferencesFile, that holds settings and pointers to private data; typically accessible only to the agent or a delegate.
+
WebID Profile
+
The RDF graph [RDF11-CONCEPTS] formed by the set union of statements drawn from the WebID Profile Document, any Extended Profile Documents, the Preferences Document, and the Type Index documents, assembled per the common assumptions below.
+
+ +
+

Requirements derivable from Solid26 Implementation Guide specifications

+
+
    +
  1. + A WebID is an HTTP URI denoting an agent [WebID 1.0 § Terminology]. +
    2. +
  2. + The WebID Profile Document is obtained by dereferencing the WebID HTTP URI: for a WebID with a fragment (e.g. #me), the fragment-less URI identifies it; for a WebID without a fragment, an HTTP GET MUST return 303 See Other whose Location identifies it [WebID 1.0 § Terminology, § The WebID HTTP URI]. +
    3. +
  3. + A WebID Document MAY be hosted anywhere on the Web, in or out of Solid storage [WebID 1.0 § Publishing the WebID Profile Document]. +
      +
    • A Solid client can only modify a WebID Profile if the underlying document is in a Solid storage. When the WebID Document is not in a Solid storage, it is recommended to link at least one Extended Profile Document that is, so that clients can attach further profile statements by writing to it.
      • +
    +
    4. +
  4. + The WebID Profile Document MUST be available in text/turtle and application/ld+json [WebID 1.0 § Publishing the WebID Profile Document; Solid WebID Profile § Reading Profile]. +
    5. +
  5. + The WebID Profile MUST contain at least one statement <webid> solid:oidcIssuer <iss>, where <iss> is an OpenID Provider trusted to issue ID Tokens for the WebID [Solid-OIDC § OIDC Issuer Discovery]. +
    6. +
  6. + Solid storages owned by the agent MAY be advertised in the WebID Profile via <webid> pim:storage <storage> [Solid Protocol § Storage]. +
    7. +
  7. + An agent MAY advertise a Linked Data Notifications inbox via <webid> ldp:inbox <inbox>; other agents post notifications there [Solid WebID Profile § WebID Profile Data Model; Solid Protocol § Linked Data Notifications]. +
    8. +
+
+
+ +
+

Common assumptions not required by Solid26 Implementation Guide specifications

+
+
    +
  1. + The WebID Document is a public resource (i.e. an unauthenticated HTTP GET on the WebID URI returns the Profile) [WebID 1.0 § Processing the WebID Profile]. +
      +
    • These specifications do not preclude authenticated retrieval of a non-public WebID Document by a server acting as a client, though current server implementations generally do not support it.
      • +
    +
    2. +
  2. + The pim:storage statement in the WebID Profile is the only sound mechanism for discovering an agent's storages. The storageDescription Link header is not to be used for this purpose: a WebID Document hosted in a storage does not imply the WebID owns that storage [Solid Protocol § Privacy Considerations]. +
    3. +
  3. + The WebID Profile is assembled by collecting all statements that have the WebID as subject or object, drawn from the WebID Document and from any Extended Profile Document linked from it via rdfs:seeAlso, foaf:isPrimaryTopicOf, or owl:sameAs (collectively, discovery links) [Solid WebID Profile § Discovery; Solid WebID Profile § Extending a Profile; WebID 1.0 § Processing the WebID Profile]. Extended Profile Documents may require authenticated retrieval. One caveat applies: +
      +
    • solid:oidcIssuer is honoured only from the WebID Document; statements of the form ?webid solid:oidcIssuer ?iss in Extended Profile Documents are ignored.
      • +
    +
    4. +
+
+
+ +
+

Assembling the Profile

+
+ +

Per [Solid WebID Profile § Discovery], the full profile is the union of statements in:

+
    +
  • the WebID Profile Document;
    • +
  • Extended Profile Documents directly linked from the WebID Document via discovery links, and Extended Profile Documents that those in turn link by discovery links;
    • +
  • the agent's Preferences Document (linked via pim:preferencesFile) and the Extended Profile Documents it links by discovery links;
    • +
  • the agent's public and private Type Index documents (linked via solid:publicTypeIndex and solid:privateTypeIndex).
    • +
+ +

To assemble it:

+
    +
  1. GET the WebID Document. If it cannot be retrieved, surface a clear error.
    2. +
  2. GET each linked document: Extended Profile Documents via discovery links, the Preferences Document via pim:preferencesFile, and Type Index documents via solid:publicTypeIndex/solid:privateTypeIndex. On 401/403 with a logged-in user, retry authenticated; Preferences and the private Type Index normally require authentication [Solid WebID Profile § Discovery, § Private Preferences]. If the WebID Document does not link a Preferences Document or Type Index documents, those fetches are skipped; their absence is not an error.
    3. +
  3. For each Extended Profile Document linked directly from the WebID Document, fetch the Extended Profile Documents it links via its discovery links. 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.
    4. +
  4. Form the set union of statements from the fetched documents, then drop every solid:oidcIssuer triple that did not originate in the WebID Document: that predicate is authoritative only when sourced there, mirroring the write protection in Solid WebID Profile § Updating Profile. Other discovery predicates (e.g. pim:storage, ldp:inbox) may legitimately appear in any of these documents.
    5. +
  5. Retain only statements that have the WebID as subject or object [Solid WebID Profile § Discovery].
    6. +
+ +
+

Note

+

When the WebID Document is not hosted in Solid storage, clients cannot add new discovery links 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.

+
+ +
+
+ +
+
+
+
+ +
+

Guidance for clients

+
+ +

This section targets clients acting on behalf of a single end user — reading and writing the user's data — as opposed to authorization agents, profile editors, or server-side resource servers. The recommended flow is:

+ +
    +
  1. +

    Obtain the user's WebID. Prompt for a WebID URI and validate that it is a well-formed http/https URI. Surface clear errors for malformed input, 404s, and responses that cannot be parsed as RDF.

    +
    2. +
  2. +

    Dereference the WebID. Issue an unauthenticated GET on the WebID URI. The 303 See Other redirect to the WebID Document is expected per the "Cool URIs for the Semantic Web" pattern, but other 3xx codes (301, 302, 307, 308) may also occur and must be handled.

    +
    3. +
  3. +

    Authenticate the user via their OpenID Provider. Read ?webid solid:oidcIssuer ?iss from the WebID Document. If no solid:oidcIssuer statement is present, surface a clear error: the WebID is not usable for Solid authentication. If more than one issuer is listed, let the user choose. Before initiating the Solid-OIDC login flow, fetch the issuer's OpenID Connect Discovery 1.0 configuration and verify that webid appears in scopes_supported [Solid-OIDC § OIDC Issuer Discovery, § OpenID Provider Conformance].

    +
    4. +
  4. +

    Build the WebID Profile graph by running Assembling the Profile (do not discover storages via the solid:storageDescription Link header).

    +
    5. +
+ +
+

Note

+

pim:storage may yield more than one value. When the application needs exactly one storage to write data into, prompt the user to choose rather than picking one silently.

+
+ +
+

Note

+

The Solid WebID Profile [WEBID-PROFILE] does not standardise predicates for rendering an agent's identity. For empirical data on which predicates are actually populated across the ecosystem, implementers can consult solid-load-profile, which summarises predicate usage from a sample of live Solid profiles. The list below targets foaf:Person, vcard:Individual, and schema:Person, drawing from the predicates read by existing profile renderers including SolidOS/mashlib, PodOS, Penny, and dokieli. Vocabularies referenced: FOAF [FOAF], vCard [VCARD-RDF], Schema.org [SCHEMA-ORG], ActivityStreams, SIOC, Org, and Solid Terms.

+

The following is a list of fallback predicates that applications may wish to consider using when rendering a profile. The order given for each field is a suggested preference; other orderings may be more appropriate depending on the ecosystem the application integrates with.

+
    +
  • Name: foaf:name, with fallbacks to schema:name, vcard:fn, as:name, or rdfs:label. For structured names: schema:givenName+schema:familyName, foaf:givenName+foaf:familyName, or vcard:given-name+vcard:family-name.
    • +
  • Short name / nickname: foaf:nick, with fallback to vcard:nickname.
    • +
  • Avatar / photo: vcard:hasPhoto, with fallbacks to as:image, as:icon, foaf:img, schema:image, vcard:photo, sioc:avatar, or foaf:depiction.
    • +
  • Email: vcard:hasEmail, with fallbacks to schema:email or foaf:mbox.
    • +
  • Telephone: vcard:hasTelephone.
    • +
  • Address: vcard:hasAddress (with vcard:country-name, vcard:locality on the value).
    • +
  • Description / bio: vcard:note, with fallback to schema:description.
    • +
  • Birthday: vcard:bday.
    • +
  • Organization & role: vcard:organization-name and vcard:role; for richer involvement, org:organization/org:member and org:role, or schema:hasOccupation.
    • +
  • Pronouns: solid:preferredSubjectPronoun, solid:preferredObjectPronoun, solid:preferredRelativePronoun.
    • +
  • Skills: schema:skills, with fallback to cco:skill.
    • +
  • Languages: vcard:language, with fallbacks to schema:knowsLanguage or solid:preferredLanguage.
    • +
  • Friends / contacts: foaf:knows, with fallback to schema:knows.
    • +
  • Profile colours: solid:profileHighlightColor, solid:profileBackgroundColor.
    • +
  • Homepage / web page: foaf:homepage, foaf:weblog, schema:url, or vcard:url.
    • +
  • Social accounts: foaf:account, with account nodes carrying foaf:accountName and foaf:userProfilePrefix.
    • +
+

None of these are guaranteed to be present; UIs should fall back to the WebID URI when no human-readable label is available.

+
+ +
+

Note

+

Data discovery beyond the profile varies across the ecosystem. Mechanisms in active use include: Type Indexes; Solid Application Interoperability (SAI); SPARQL or Quad Pattern Fragments endpoints; fixed paths under the root of a storage; and DCAT catalogues. This guide does not prescribe a single mechanism.

+
+ +
+
+ +
+

Security and Privacy Considerations

+
+ +
+

Note

+

Drafted with generative-AI assistance to kickstart coverage; community review is expected.

+
+ +
    +
  • Protected Properties in WebID Profile Documents. Servers are strongly encouraged to protect the § Protected properties in a Solid WebID Profile document such that non-owner agents with write access to the document cannot change the issuer.
    • +
  • Authorization authorizes agents, not applications. WAC and ACP both grant access to the agent (WebID) behind a request. Any application acting as that agent inherits its access. WAC has no mechanism to constrain by application; ACP's Client matcher has limited practical coverage (demonstration). CG work on conditional grants is in progress.
    • +
  • Consent transitivity in access control. Access-control and group resources can themselves carry personal data. Any agent with acl:Control on such a resource can read that data; consent to include someone in an ACL is transitive to every Control holder [WAC § Security and Privacy Review].
    • +
  • Client identity. Solid-OIDC has no mechanism for strongly-asserted client identity, and browser-based clients cannot hold client secrets. Authorization Servers treat anonymous clients with low-trust policies; confidential-client protections are unavailable in typical SPA deployments [Solid-OIDC § Out of Scope, § Client Secrets].
    • +
+ +
+
+ +
+

References

+
+
+
[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
+ +
[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
+ +
[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
+ +
[WEBID]
+
WebID 1.0. Andrei Sambra; Stéphane Corlosquet. W3C WebID Community Group. 5 March 2014. W3C Editor's Draft. URL: https://www.w3.org/2005/Incubator/webid/spec/identity/
+ +
[WEBID-PROFILE]
+
Solid WebID Profile. Virginia Balseiro; Jeff Zucker; Sarven Capadisli (eds.). Tim Berners-Lee; Sarven Capadisli; Virginia Balseiro; Timea Turdean; Jeff Zucker (authors). W3C Solid Community Group. 12 May 2024. Draft Community Group Report, Version 1.0.0. URL: https://solid.github.io/webid-profile/
+ +
[RDF11-CONCEPTS]
+
RDF 1.1 Concepts and Abstract Syntax. Richard Cyganiak; David Wood; Markus Lanthaler. W3C. 25 February 2014. W3C Recommendation. URL: https://www.w3.org/TR/rdf11-concepts/
+ +
[FOAF]
+
FOAF Vocabulary Specification 0.99. Dan Brickley; Libby Miller. 14 January 2014. URL: http://xmlns.com/foaf/spec/
+ +
[VCARD-RDF]
+
vCard Ontology - for describing People and Organizations. Renato Iannella; James McKinney. W3C. 22 May 2014. W3C Working Group Note. URL: https://www.w3.org/TR/vcard-rdf/
+ +
[SCHEMA-ORG]
+
Schema.org. W3C Schema.org Community Group. URL: https://schema.org/
+ +
[BKY+24]
+
+ AuthApp - Portable, Reusable Solid App for GDPR-Compliant Access Granting. + Andreas Both; Thorsten Kastner; Dustin Yeboah; Christoph Braun; Daniel Schraudner; Sebastian Schmid; Tobias Käfer; Andreas Harth. + ICWE 2024: 199-214. + URL: https://publikationen.bibliothek.kit.edu/1000172187/post +
+
+
+
+ +
+
+
+ +