The Solid Ecosystem

Editor’s Draft,

This version:
https://solid.github.io/specification/
Issue Tracking:
GitHub
Inline In Spec
Editor:
Your Name (Your Company)

Abstract

This document connects a set of specifications that, together, provide applications with secure and permissioned access to externally stored data in an interoperable way.

Status of This Document

This document is an incomplete draft. The sections that have been incorporated have been reviewed following the Solid process. However, the information in this document is still subject to change.

You are invited to contribute any feedback, comments, or questions you might have.

1. Introduction

Write Introduction section.

Explain the principle of orthogonality, by which this spec is split into multiple documents.

Explain that this specification is not documentation; it is the easiest way to understand how Solid works, not the easiest way for building a Solid app.

1.1. Definitions

A data pod is a place for storing documents, with mechanisms for controlling who can access what.

A Solid app is an application that reads or writes data from one or more data pods.

Introduce the structure of this document. Cross-server interoperability Cross-app interoperability

1.2. Namespaces

Prefix Namespace Description
rdf http://www.w3.org/1999/02/22-rdf-syntax-ns# [rdf-schema]
ldp http://www.w3.org/ns/ldp# [LDP]
solid http://www.w3.org/ns/solid/terms# Solid Terms

2. Authenticated Resource Access

Write introduction to the Authenticated Resource Access section.

2.1. Hypertext Transfer Protocol

2.1.1. Background and Need

This section is non-normative.

Solid clients and servers need to exchange data securely over the Internet, and they do so using the HTTP Web standard. This section describes in detail which parts of HTTP must be implemented by clients and servers.

2.1.2. Required server-side implementation

A data pod MUST be an HTTP/1.1 server [RFC7230][RFC7231]. It SHOULD additionally be an HTTP/2 server [RFC7540] to improve performance, especially in cases where individual clients are expected to send high numbers of successive requests.

A data pod SHOULD use TLS connections through the https URI scheme in order to secure the communication between clients and servers. When both http and https are supported, all http URIs MUST redirect to their https counterparts using a response with a 301 status code and a Location header.

A data pod MUST implement the server part of HTTP/1.1 Conditional Requests [RFC7232] to ensure that updates requested by clients will only be applied if given preconditions are met. It SHOULD additionally implement the server part of HTTP/1.1 Caching [RFC7234] to improve performance. A data pod MAY implement the server part of HTTP/1.1 Range Requests [RFC7233] to further improve performance for large representations.

A data pod MUST implement the server part of HTTP/1.1 Authentication [RFC7235]. When a client does not provide valid credentials when requesting a resource that requires it (see § 2.3 WebID), the data pod MUST send a response with a 401 status code (unless 404 is preferred for security reasons).

2.1.3. Required client-side implementation

A Solid client MUST be an HTTP/1.1 client [RFC7230][RFC7231]. It MAY additionally be an HTTP/2 client [RFC7540] to improve performance.

A Solid client MAY implement the client parts of HTTP/1.1 Conditional Requests [RFC7232] to only trigger updates when certain preconditions are met. It MAY implement HTTP/1.1 Caching [RFC7234] and HTTP/1.1 Range Requests [RFC7233] to improve performance.

A Solid client MUST implement the client part of HTTP/1.1 Authentication [RFC7235] if it needs to access resources requiring authentication (see § 2.3 WebID). When it receives a response with a 403 or 404 status code, it MAY repeat the request with different credentials.

2.2. Linked Data Platform

Write Linked Data Platform section.

Draft: A Solid data pod MUST conform to the LDP specification [LDP].

2.3. WebID

Explain inline that agents accessing non-public Solid resources need to authenticate with a WebID, which is a URL pointing to a document with an RDF representation.

2.3.1. WebID-OIDC

Write WebID-OIDC section.

Draft: A Solid data pod MUST conform to the WebID-OIDC specification [WEBID-OIDC].

2.3.2. WebID-TLS

Write WebID-TLS section.

Draft: A Solid data pod MAY conform to the WebID-TLS specification [WEBID-TLS].

2.4. Web Access Control

Write Web Access Control section.

Draft: A Solid data pod MUST conform to the Web Access Control specification [WAC].

2.5. Cross-Origin Resource Sharing

2.5.1. Background and Need

This section is non-normative.

Solid apps typically access data from multiple sources. However, Web browsers by default prevent apps that run on one origin from accessing data on other origins. This cross-origin protection is a security mechanism that ensures malicious websites cannot simply read your profile or banking details from other websites. However, this reasonable default poses a problem even for benevolent Solid apps, which might have good reasons to access data from different places. For instance, a Solid app at https://app.example/ would be prevented from accessing data on https://alice-data-pod.example/ or https://bob-data-pod.example/, even when Alice and Bob have given the user of the app their permission to see some of their data.

For cases where the other origins have their own access protection mechanism—like within Solidthe browser’s built-in cross-origin protection is actually an obstacle rather than a feature. After all, data pods already ensure through access control that certain documents can only be accessed by specific people or applications. Preventively blocking apps from different origins thus introduces an unnecessary barrier.

Fortunately, Web servers can indicate to the browser that certain documents do not require cross-origin protection. This mechanism to selectively disable that protection is called Cross-Origin Resource Sharing or CORS [FETCH]. By responding to browser requests with a specific combination of HTTP headers, servers can indicate which actions are allowed for a given resource. For a Solid data pod, the goal is to allow all actions on the CORS level, such that the deeper access control layer can exert full control over the app’s allowed permissions. The next section describes how to achieve this through the right HTTP header configuration.

2.5.2. Required server-side implementation

A data pod MUST implement the CORS protocol [FETCH] such that, to the extent possible, the browser allows Solid apps to send any request and combination of request headers to the data pod, and the Solid app can read any response and response headers received from the data pod. If the data pod wishes to block access to a resource, this MUST NOT happen via CORS but MUST instead be communicated to the Solid app in the browser through HTTP status codes such as 401, 403, or 404 [RFC7231].

Note: Since the CORS protocol is part of a Living Standard, it might be changed at any point, which might necessitate changes to data pod implementations for continued prevention of undesired blocking. A proposal to mitigate this has been suggested.

Concretely, whenever a data pod receives an HTTP request containing a valid Origin header [RFC6454], the server MUST respond with the appropriate Access-Control-* headers as specified in the CORS protocol [FETCH]. In particular, the data pod MUST set the Access-Control-Allow-Origin header to the valid Origin value from the request and list Origin in the Vary header value. The data pod MUST make all used response headers readable for the Solid app through Access-Control-Expose-Headers (with the possible exception of the Access-Control-* headers themselves). A data pod MUST also support the HTTP OPTIONS method [RFC7231] such that it can respond appropriately to CORS preflight requests.

Careful attention is warranted, especially because of the many edge cases. For instance, data pods SHOULD explicitly enumerate all used response headers under Access-Control-Expose-Headers rather than resorting to *, which does not cover all cases (such as credentials mode set to include). Data pods SHOULD also explicitly list Accept under Access-Control-Allow-Headers, because values longer than 128 characters (not uncommon for RDF-based Solid apps) would otherwise be blocked, despite shorter Accept headers being allowed without explicit mention.

3. Clients and Apps

Write introduction to the Clients and Apps section.

3.1. Implementation Guidance

This section is non-normative.

Write Implementation Guidance section.

3.2. Data Shapes and Footprints

Write introduction to Data Shapes and Footprints section.

3.2.1. Data Shapes

Write Data Shapes section.

Draft: A Solid client MUST conform to the SHACL specification [SHACL].

SHACL or ShEx?

3.2.2. Footprints

Write Footprints section.

Draft: A Solid client MUST conform to the Data Footprints specification [FOOTPRINTS].

3.3. Data Shape Guidance

This section is non-normative.

Write Data Shape Guidance section.

3.4. Update Notifications

Write Update Notification section.

Draft: A Solid client MUST conform to the LDN specification [LDN].

4. Optional Integrations

Write introduction to the Optional Integrations section.

4.1. Pod and User Management

Write Pod and User Management section.

Draft: A Solid data pod MAY conform to the Pod Management specification [POD-MANAGEMENT].

4.2. Query Interfaces

Write Query Interfaces section.

Draft: A Solid data pod MAY conform to the Triple Pattern Fragments specification [TPF].

4.3. Additional Content Negotiation Dimensions

Write Additional Content Negotiation Dimension section.

4.3.1. Memento

Write Memento section.

Draft: A Solid data pod MAY conform to the Memento specification [RFC7089].

4.3.2. Profiles

Write Profiles section.

Draft: A Solid data pod MAY conform to the Profile-based Content Negotiation specification [PROFILES].

4.4. Verifiable Credentials

Write Verifiable Credentials section.

Draft: A Solid data pod MAY conform to the Verifiable Credentials specification [VERIFIABLE-CREDENTIALS].

5. Security Considerations

Some of the normative references with this specification point to documents with a Living Standard status, meaning their contents can still change over time. It is advised to monitor these documents, as such changes might have security implications.

A data pod MUST NOT assume that HTTP request headers sent by a client are valid, and MUST reject or sanitize invalid header values before processing them or incorporating them in messages sent to others. For example, values for Host and Origin MUST NOT be assumed to be free of possibly malicious sequences such as /.. or others, and invalid Origin values MUST NOT be echoed into the Access-Control-Allow-Origin response header.

A data pod MUST NOT assume that the user agent is a regular Web browser, even when requests contain familiar values in headers such as User-Agent or Origin. Such an assumption could lead to incorrect conclusions about the security model of the application making the request, since the request might actually come from a non-browser actor unaffected by browser security constraints.

Solid data pods disable all cross-origin protections in browsers because resource access is governed explicitly by Web Access Control. As such, data pods MUST NOT rely on browser-based cross-origin protection mechanisms for determining the authentication status or representation of a resource. In particular, they MUST ignore HTTP cookies from untrusted origins. Additional security measures MAY be taken to prevent metadata in error responses from leaking. For instance, a malicious app could probe multiple servers to check whether the response status code is 401 or 403, or could try to access an error page from an intranet server within the user agent’s private network to extract company names or other data. To mitigate this, when a request from an untrusted Origin arrives, the data pod MAY set the status code of error responses to 404 and/or anonymize or censor their contents.

Data pods SHOULD use TLS connections to protect the contents of requests and responses from eavesdropping and modification by third parties. Unsecured TCP connections without TLS MAY be used in testing environments or when the data pod is behind a reverse proxy that terminates a secure connection.

5.1. Privacy Considerations

Write Privacy Considerations section.

5.1.1. Identifiable Information

Write Identifiable Information section.

In order to prevent leakage of non-resource data, error responses SHOULD NOT contain identifiable information.

Conformance

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

Index

Terms defined by this specification

References

Normative References

[FETCH]
Anne van Kesteren. Fetch Standard. Living Standard. URL: https://fetch.spec.whatwg.org/
[FOOTPRINTS]
Data Footprints. URL: https://solid.github.io/specification/footprints/
[LDN]
Sarven Capadisli; Amy Guy. Linked Data Notifications. 2 May 2017. REC. URL: https://www.w3.org/TR/ldn/
[LDP]
Steve Speicher; John Arwe; Ashok Malhotra. Linked Data Platform 1.0. 26 February 2015. REC. URL: https://www.w3.org/TR/ldp/
[POD-MANAGEMENT]
Data Pod Management. URL: https://solid.github.io/specification/pod-management/
[PROFILES]
Lars Svensson; Ruben Verborgh. Indicating and Negotiating Profiles in HTTP. URL: https://profilenegotiation.github.io/I-D-Profile-Negotiation/I-D-Profile-Negotiation.html
[RDF-SCHEMA]
Dan Brickley; Ramanathan Guha. RDF Schema 1.1. 25 February 2014. REC. URL: https://www.w3.org/TR/rdf-schema/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[RFC6454]
A. Barth. The Web Origin Concept. December 2011. Proposed Standard. URL: https://tools.ietf.org/html/rfc6454
[RFC7089]
H. Van de Sompel; M. Nelson; R. Sanderson. HTTP Framework for Time-Based Access to Resource States -- Memento. December 2013. Informational. URL: https://tools.ietf.org/html/rfc7089
[RFC7230]
R. Fielding, Ed.; J. Reschke, Ed.. Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7230.html
[RFC7231]
R. Fielding, Ed.; J. Reschke, Ed.. Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7231.html
[RFC7232]
R. Fielding, Ed.; J. Reschke, Ed.. Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7232.html
[RFC7233]
R. Fielding, Ed.; Y. Lafon, Ed.; J. Reschke, Ed.. Hypertext Transfer Protocol (HTTP/1.1): Range Requests. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7233.html
[RFC7234]
R. Fielding, Ed.; M. Nottingham, Ed.; J. Reschke, Ed.. Hypertext Transfer Protocol (HTTP/1.1): Caching. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7234.html
[RFC7235]
R. Fielding, Ed.; J. Reschke, Ed.. Hypertext Transfer Protocol (HTTP/1.1): Authentication. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7235.html
[RFC7540]
M. Belshe; R. Peon; M. Thomson, Ed.. Hypertext Transfer Protocol Version 2 (HTTP/2). May 2015. Proposed Standard. URL: https://httpwg.org/specs/rfc7540.html
[SHACL]
Holger Knublauch; Dimitris Kontokostas. Shapes Constraint Language (SHACL). 20 July 2017. REC. URL: https://www.w3.org/TR/shacl/
[TPF]
Ruben Verborgh. Triple Pattern Fragments. URL: https://www.hydra-cg.com/spec/latest/triple-pattern-fragments/
[VERIFIABLE-CREDENTIALS]
Manu Sporny; Dave Longley; David Chadwick. Verifiable Credentials Data Model 1.0. URL: https://www.w3.org/TR/verifiable-claims-data-model/
[WAC]
Web Access Control. URL: https://solid.github.io/specification/wac/
[WEBID-OIDC]
WebID-OIDC. URL: https://solid.github.io/specification/webid-oidc/
[WEBID-TLS]
WebID-TLS. URL: https://solid.github.io/specification/webid-tls/

Issues Index

Write Introduction section.
Explain the principle of orthogonality, by which this spec is split into multiple documents.
Explain that this specification is not documentation; it is the easiest way to understand how Solid works, not the easiest way for building a Solid app.
Introduce the structure of this document. Cross-server interoperability Cross-app interoperability
Write introduction to the Authenticated Resource Access section.
Write Linked Data Platform section.
Explain inline that agents accessing non-public Solid resources need to authenticate with a WebID, which is a URL pointing to a document with an RDF representation.
Write WebID-OIDC section.
Write WebID-TLS section.
Write Web Access Control section.
Write introduction to the Clients and Apps section.
Write Implementation Guidance section.
Write introduction to Data Shapes and Footprints section.
Write Data Shapes section.
SHACL or ShEx?
Write Footprints section.
Write Data Shape Guidance section.
Write Update Notification section.
Write introduction to the Optional Integrations section.
Write Pod and User Management section.
Write Query Interfaces section.
Write Additional Content Negotiation Dimension section.
Write Memento section.
Write Profiles section.
Write Verifiable Credentials section.
Write Privacy Considerations section.
Write Identifiable Information section.