Solid Protocol

https://solidproject.org/TR/protocol
Admin
This document connects a set of specifications that provide applications with secure and...
Tokens:12,239
Snippets:89
Trust Score:9.6
Update:9 months ago
Show doc for...
Tokens:
Raw
### N3 Patch Example for Renaming a Resource

Source: https://solidproject.org/TR/protocol/index

An example of an N3 Patch document used to rename a resource. It specifies conditions for deletion and triples to be inserted, demonstrating a conditional update operation.

```n3
@prefix solid: <http://www.w3.org/ns/solid/terms#>.
@prefix ex: <http://www.example.org/terms#>.

_:rename a solid:InsertDeletePatch;
  solid:where   { ?person ex:familyName "Garcia". };
  solid:inserts { ?person ex:givenName "Alex". };
  solid:deletes { ?person ex:givenName "Claudia". }.
```

--------------------------------

### Resource Reading Operations

Source: https://solidproject.org/TR/protocol/index

Servers must support GET, HEAD, and OPTIONS methods for reading resources and determining communication options. The Allow header indicates supported methods.

```APIDOC
## Resource Reading Operations

### Description
Servers MUST support the HTTP `GET`, `HEAD` and `OPTIONS` methods for clients to read resources or to determine communication options. Servers MUST indicate the HTTP methods supported by the target resource by generating an `Allow` header field in successful responses.

### Method
`GET`, `HEAD`, `OPTIONS`

### Endpoint
`/{resource-uri}`

### Parameters
None

### Request Example
```http
OPTIONS /my-document.ttl HTTP/1.1
Host: example.com
```

### Response
#### Success Response (200/204)
- **Allow** (header) - Lists the HTTP methods supported by the resource (e.g., `GET, HEAD, OPTIONS, PUT, DELETE`).
- **Accept-Patch**, **Accept-Post**, **Accept-Put** (headers) - Indicate supported media types for corresponding methods if applicable.

#### Response Example
```http
HTTP/1.1 200 OK
Allow: GET, HEAD, OPTIONS, PUT, DELETE
Accept-Put: text/turtle

```
```

--------------------------------

### Discovering Auxiliary Resources

Source: https://solidproject.org/TR/protocol/index

Servers must advertise auxiliary resources via the HTTP Link header in responses to HEAD and GET requests. Clients can discover these resources by inspecting this header.

```APIDOC
## Discovering Auxiliary Resources

### Description
Servers MUST advertise auxiliary resources associated with a subject resource by responding to `HEAD` and `GET` requests by including the HTTP `Link` header field with the `rel` parameter [RFC8288]. Clients can discover auxiliary resources by making an HTTP `HEAD` or `GET` request on the target URL, and checking the HTTP `Link` header field.

### Method
`HEAD`, `GET`

### Endpoint
`/{subject-resource-uri}`

### Parameters
None

### Request Example
```http
HEAD /my-document.ttl HTTP/1.1
Host: example.com
Accept: text/turtle
```

### Response
#### Success Response (200/204)
- **Link** (header) - Contains URIs of auxiliary resources with their respective relation types (e.g., `rel="acl"`, `rel="describedby"`).

#### Response Example
```http
HTTP/1.1 200 OK
Content-Type: text/turtle
Link: </.acl>; rel="acl", </.meta>; rel="describedby"

@prefix ex: <http://example.org/> .

ex:my-document
  a ex:Document .
```
```

--------------------------------

### Storage Resource Discovery and Interaction

Source: https://solidproject.org/TR/protocol/index

This section describes how clients can discover and interact with storage resources, including how to identify a storage and retrieve its description.

```APIDOC
## Storage Resource

### Description
Servers MUST provide one or more storages. The storage resource (`pim:Storage`) is the root container for all of its contained resources. Servers MUST advertise the storage resource by including the HTTP `Link` header field with `rel="type"` targeting `http://www.w3.org/ns/pim/space#Storage` when responding to storage’s request URI.

### How to Identify a Storage Resource
Clients can determine a resource is of type storage by making an HTTP `HEAD` or `GET` request on the target URL, and checking for the `Link` header field with `rel="type"` targeting `http://www.w3.org/ns/pim/space#Storage`.

### How to Find the Storage of a Resource
Clients can determine the storage of a resource by moving up the URI path hierarchy until the response includes a `Link` header field with `rel="type"` targeting `http://www.w3.org/ns/pim/space#Storage`.

### How to Discover a Storage
Clients can discover a storage by making an HTTP `GET` request on the target URL to retrieve an RDF representation. The encoded RDF graph contains a relation of type `http://www.w3.org/ns/pim/space#storage`. The object of the relation is the storage (`pim:Storage`).

### Storage Description
Servers MUST include the `Link` header field with `rel="http://www.w3.org/ns/solid/terms#storageDescription"` targeting the URI of the storage description resource in the response of HTTP `GET`, `HEAD` and `OPTIONS` requests targeting a resource in a storage.

Servers MUST include statements about the storage as part of the storage description resource. These include:

- `rdf:type`: A class whose URI is `http://www.w3.org/ns/pim/space#Storage`.

### Owner Information
Servers MUST keep track of at least one owner of a storage. When advertising the owner, servers MUST include the `Link` header field with `rel="http://www.w3.org/ns/solid/terms#owner"` targeting the URI of the owner in the response of HTTP `HEAD` or `GET` requests targeting the root container.
```

--------------------------------

### Resource Manipulation (PUT, POST, PATCH)

Source: https://solidproject.org/TR/protocol/index

This section details the required and optional HTTP methods for interacting with Solid resources, including creation, updates, and container management.

```APIDOC
## Resource Manipulation (PUT, POST, PATCH)

### Description
Servers MUST support the HTTP `PUT`, `POST`, and `PATCH` methods for resource manipulation. This includes creating intermediate containers, handling resource creation via POST, and managing auxiliary resources.

### Methods
- `PUT`
- `POST`
- `PATCH`

### Endpoint
- `/websites/solidproject_tr_protocol` (and sub-paths)

### Behavior Details

- **Intermediate Containers**: Servers MUST create intermediate containers and include corresponding containment triples in container representations derived from the URI path component of `PUT` and `PATCH` requests.
- **Resource Creation**: Servers MUST allow creation of new resources by a `POST` request to a URI path ending with `/`. Servers MUST create resources with URI paths ending with `/{id}` in container `/`.
- **POST to Non-existent Resource**: When a `POST` method request targets a resource without an existing representation, the server MUST respond with the `404` status code.
- **Auxiliary Resources**: When a `PUT` or `PATCH` request targets an auxiliary resource, the server MUST create or update it.
- **Container Updates**: Servers MUST NOT allow HTTP `PUT` or `PATCH` on a container to update its containment triples; if the server receives such a request, it MUST respond with a `409` status code.
- **Container Metadata**: Servers MUST NOT allow HTTP `POST`, `PUT`, and `PATCH` to update a container’s resource metadata statements; if the server receives such a request, it MUST respond with a `409` status code.
```

--------------------------------

### Resource Containment and Container Metadata

Source: https://solidproject.org/TR/protocol/index

This section explains the concept of containers in Solid for resource discovery and lifecycle management, and how servers can provide metadata about contained resources.

```APIDOC
## Resource Containment

### Description
Solid uses containers to group linked resources, aiding in discovery and management. There's a direct relationship between containment triples and the hierarchical structure of URIs, ensuring all resources are discoverable from a container.

### Container Representation
The representation and behavior of containers in Solid correspond to LDP Basic Container and MUST be supported by the server.

### Container Last-Modified Header
Servers can determine the `Last-Modified` field value for containers based on changes to containment triples. However, changes to other parts of the container do not affect this value, and it cannot be reliably used for change detection.

### Contained Resource Metadata
Servers SHOULD include resource metadata about contained resources as part of the container description, unless inapplicable.

Contained resource metadata statements include:

- `rdf:type`: A class whose URI is the expansion of the URI Template `http://www.w3.org/ns/iana/media-types/{+iana-media-type}#Resource`, where `iana-media-type` is from IANA Media Types.
- `stat:size`: The size of the resource in bytes (non-negative integer).
- `dcterms:modified`: The date and time when the resource was last modified.
- `stat:mtime`: The Unix time when the resource was last modified.

The `dcterms:modified` value corresponds to the `Last-Modified` header field value of the contained resource if a `HEAD` or `GET` request were made at the time of generation.

**Note:** Generation of contained resource metadata may be inapplicable to some servers. This metadata is protected by the server.
```

--------------------------------

### HTTP Client Requirements

Source: https://solidproject.org/TR/protocol/index

Outlines the mandatory and recommended HTTP specifications for Solid Protocol clients, covering semantics, caching, and version compatibility.

```APIDOC
## HTTP Client Requirements

### Description
Clients MUST conform to HTTP Semantics [RFC9110]. Clients MAY conform to HTTP Caching [RFC9111]. Clients MUST conform to HTTP/1.1 [RFC9112]. Clients MAY conform to HTTP/2 [RFC9113].

When a client receives a response with a `403` or `404` status code, the client MAY repeat the request with different credentials.

Clients MUST use the `Content-Type` HTTP header field in `PUT`, `POST`, and `PATCH` requests that contain content [RFC9110].
```

--------------------------------

### POST Request Behavior

Source: https://solidproject.org/TR/protocol/index

Describes the behavior of POST requests in Solid Protocol compared to LDP, particularly regarding URI generation for newly created resources.

```APIDOC
## POST Request Behavior Comparison with LDP

### Description
LDP does not specify URI patterns for resources when using the `POST` method. In contrast, Solid Protocol dictates that the URI of a new resource resulting from a `POST` request is determined contextually by the request URI, ensuring predictable URI creation within the direct hierarchy. This server behavior is compatible with LDP, allowing Solid Protocol servers to be a specialization of LDP.
```

--------------------------------

### HTTP Server Requirements

Source: https://solidproject.org/TR/protocol/index

Details the mandatory and recommended HTTP specifications that Solid Protocol servers must adhere to, including semantics, caching, and version compatibility.

```APIDOC
## HTTP Server Requirements

### Description
Servers MUST conform to HTTP Semantics [RFC9110]. Servers SHOULD conform to HTTP Caching [RFC9111]. Servers MUST conform to HTTP/1.1 [RFC9112]. Servers SHOULD conform to HTTP/2 [RFC9113].

Servers SHOULD use TLS connections through the `https` URI scheme in order to secure the communication with clients. When both `http` and `https` URI schemes are supported, the server MUST redirect all `http` URIs to their `https` counterparts using a response with a `301` status code and a `Location` header field.

When a client does not provide valid credentials when requesting a resource that requires it (see WebID), servers MUST send a response with a `401` status code (unless `404` is preferred for security reasons).

Server MUST generate a `Content-Type` header field in a message that contains content.

Server MUST reject `PUT`, `POST`, and `PATCH` requests that contain content but lack the `Content-Type` header field, with a status code of `400`.
```

--------------------------------

### Resource Creation and URI Assignment

Source: https://solidproject.org/TR/protocol/index

When creating new resources, servers assign a URI. Clients can use PUT/PATCH to assign URIs, or POST for server-assigned URIs.

```APIDOC
## Resource Creation and URI Assignment

### Description
When creating new resources, servers can determine a target URI’s type by examining the URI path ending. When a successful `POST` request creates a resource, the server MUST assign a URI to that resource. Clients can use `PUT` and `PATCH` requests to assign a URI to a resource, or `POST` requests to have the server assign a URI.

### Method
`POST`, `PUT`, `PATCH`

### Endpoint
`/{container-uri}` (for POST)
`/{resource-uri}` (for PUT/PATCH)

### Parameters
#### Request Body (for POST)
- **Content** (any) - The content of the resource to be created.

#### Request Body (for PUT/PATCH)
- **Content** (any) - The content of the resource to be updated or created at the specified URI.

### Request Example (POST)
```http
POST /my-container/ HTTP/1.1
Host: example.com
Content-Type: text/turtle

<#new-resource> a <http://example.org/SomeType> .
```

### Response
#### Success Response (201 Created for POST, 200/204 for PUT/PATCH)
- **Location** (header) - URI of the newly created or updated resource.

#### Response Example (POST)
```http
HTTP/1.1 201 Created
Location: http://example.com/my-container/resource-xyz
Content-Type: text/turtle

<#new-resource> a <http://example.org/SomeType> .
```
```

--------------------------------

### Resource Representations and Redirection

Source: https://solidproject.org/TR/protocol/index

Details how servers should handle resource representations, particularly for RDF sources created via PUT, POST, or PATCH. It also covers redirection for requests targeting representation URLs different from resource URLs.

```APIDOC
## Resource Representations and Redirection

### Description
Covers how servers must provide resource representations in specified formats (text/turtle, application/ld+json) upon creation and how to handle requests targeting different representation URLs.

### Method
PUT, POST, PATCH, GET

### Endpoint
/resource

### Parameters

#### Query Parameters
- **Accept** (string) - Required for GET requests - Specifies the desired representation format (e.g., `text/turtle`, `application/ld+json`).

### Request Body
(For PUT, POST, PATCH)
- **data** (any) - The resource data to be created or updated.

### Response
#### Success Response (200 OK or 201 Created)
- **Representation** - The requested resource representation.

#### Redirection Response (307 Temporary Redirect or 308 Permanent Redirect)
- **Location** (string) - Header - Specifies the preferred URI reference when the request targets a representation URL different from the resource URL.
```

--------------------------------

### Conditional Updates (If-None-Match, ETag)

Source: https://solidproject.org/TR/protocol/index

This section explains how clients can use conditional request headers like `If-None-Match` and `ETag` to manage resource updates safely and prevent unintended modifications.

```APIDOC
## Conditional Updates (If-None-Match, ETag)

### Description
Clients are encouraged to use conditional update mechanisms to prevent unsafe modifications. This involves using the `If-None-Match: *` header to prevent overwriting existing resources and servers may use `ETag` to facilitate client-side conditional requests.

### Headers

- **`If-None-Match`** (Header - Client-side)
  - **Usage**: Clients are encouraged to use the HTTP `If-None-Match` header field with a value of `*` to prevent an unsafe request method (e.g., `PUT`, `PATCH`) from inadvertently modifying an existing representation of the target resource when the client believes that the resource does not have a current representation.

- **`ETag`** (Header - Server-side)
  - **Usage**: Servers MAY use the HTTP `ETag` header field with a strong validator for RDF bearing representations in order to encourage clients to opt-in to using the `If-Match` header field in their requests.
```

--------------------------------

### Deleting Resources

Source: https://solidproject.org/TR/protocol/index

This section details the behavior of the DELETE HTTP method for managing resources in Solid. It covers root container restrictions, handling of contained resources, and the consequences of deleting containers.

```APIDOC
## DELETE /resource

### Description
Deletes a specified resource. Servers must handle the deletion of contained resources and containers according to specific rules.

### Method
DELETE

### Endpoint
/resource

### Parameters

#### Path Parameters
- **resource** (string) - Required - The URI of the resource to delete.

### Request Body
This method does not typically have a request body.

### Response
#### Success Response (204 No Content)
- **Empty** - Indicates the resource was successfully deleted.

#### Error Response (405 Method Not Allowed)
- Returned when attempting to delete the storage's root container or its associated ACL resource.

#### Error Response (409 Conflict)
- Returned when attempting to delete a container that still contains resources.

#### Error Response (404 Not Found or 410 Gone)
- Returned for subsequent GET requests to a deleted resource.
```

--------------------------------

### Solid Notifications Protocol

Source: https://solidproject.org/TR/protocol/index

Details the Solid Notifications Protocol, which facilitates real-time communication about resource changes. It outlines the roles of Resource Servers, Subscription Servers, Notification Senders, and Notification Receivers.

```APIDOC
## Solid Notifications Protocol

### Description
This protocol enables entities in a Solid ecosystem to communicate changes affecting resources. Servers must implement Resource Server and Subscription Server, while both clients and servers can act as Notification Senders and Receivers.

### Conformance Requirements:
- **Server (Resource Server)**: MUST enable clients to discover subscription resources and notification channels.
- **Server (Subscription Server)**: MUST process and produce instructions for subscription requests.
- **Sender**: MUST produce and send messages conforming to the protocol.
- **Receiver**: MUST receive and process messages conforming to a notification channel type.

### Key Concepts:
- **Subscription Resources**: Resources clients can interact with to manage subscriptions.
- **Notification Channels**: Mechanisms for delivering notifications (e.g., WebSockets, SSE).
- **Messages**: Data exchanged within the notification protocol.
```

--------------------------------

### Web Access Control (ACL) Auxiliary Resource

Source: https://solidproject.org/TR/protocol/index

Web Access Control resources provide access control descriptions for a subject resource. They are linked via the 'acl' relation in the Link header.

```APIDOC
## Web Access Control (ACL) Auxiliary Resource

### Description
An auxiliary resource of type _Web Access Control_ provides access control description of a subject resource. It is identified by the `acl` link relation.

### Method
`GET`, `PUT`, `DELETE` (on the ACL resource itself)

### Endpoint
`/{subject-resource-uri}.acl` (typical convention)

### Parameters
None

### Request Example
```http
GET /.acl HTTP/1.1
Host: example.com
```

### Response
#### Success Response (200)
- **Content** (body) - RDF document describing access control policies (e.g., using WAC ontology).

#### Response Example
```json
{
  "example": "@prefix acl: <http://www.w3.org/ns/auth/acl#> .\n@prefix foaf: <http://xmlns.com/foaf/0.1/> .\n\n<#owner> a acl:Authorization ;\n  acl:agent foaf:me ;\n  acl:access \"read\", \"write\" ."
}
```
```

--------------------------------

### Description Resource Auxiliary Resource

Source: https://solidproject.org/TR/protocol/index

Description Resources provide descriptive metadata about a subject resource, linked via the 'describedby' relation. Servers should not associate more than one description resource per subject.

```APIDOC
## Description Resource Auxiliary Resource

### Description
An auxiliary resource of type _Description Resource_ provides a description of a subject resource. Servers MUST NOT directly associate more than one description resource to a subject resource. It is identified by the `describedby` link relation. When an HTTP request targets a description resource, the server MUST apply the authorization rule that is used for the subject resource.

### Method
`GET`, `PUT`, `DELETE` (on the Description resource itself)

### Endpoint
`/{subject-resource-uri}.meta` (typical convention)

### Parameters
None

### Request Example
```http
GET /.meta HTTP/1.1
Host: example.com
```

### Response
#### Success Response (200)
- **Content** (body) - RDF document describing the subject resource.

#### Response Example
```json
{
  "example": "@prefix dcterms: <http://purl.org/dc/terms/> .\n\n<#description> a <http://www.w3.org/2007/05/powder-s#> .\n<http://example.org/my-document> dcterms:title \"My Document\"."
}
```
```

--------------------------------

### Linked Data Notifications (LDN)

Source: https://solidproject.org/TR/protocol/index

Describes the requirements for Solid servers and clients to conform to the Linked Data Notifications (LDN) specification for receiving and sending notifications.

```APIDOC
## Linked Data Notifications (LDN)

### Description
Solid servers must implement the Receiver parts of LDN to accept notifications, and clients must implement Sender or Consumer parts to manage notifications via Inboxes.

### Conformance
- **Server**: MUST implement LDN Receiver.
- **Client**: MUST implement LDN Sender or Consumer.

### Key Operations
- **Receiving Notifications**: Servers accept notifications at a designated Inbox.
- **Sending Notifications**: Clients send notifications to an Inbox.
- **Discovering Inbox**: Clients discover the location of a resource's Inbox.
- **Retrieving Inbox Contents**: Clients retrieve notifications from an Inbox.
```

--------------------------------

### Modifying Resources Using N3 Patches

Source: https://solidproject.org/TR/protocol/index

Servers must accept PATCH requests with an N3 Patch body when the target is an RDF document. Support for N3 Patch is indicated by 'text/n3' in the 'Accept-Patch' header.

```APIDOC
## PATCH /resource/path

### Description
Modifies an RDF resource using an N3 Patch.

### Method
PATCH

### Endpoint
/resource/path

### Parameters
#### Request Body
- **N3 Patch Document** (text/n3) - Required - A document in N3 format containing patch operations.

### Request Example
```n3
@prefix solid: <http://www.w3.org/ns/solid/terms#>
@prefix ex: <http://www.example.org/terms#>

_:rename a solid:InsertDeletePatch;
  solid:where   { ?person ex:familyName "Garcia". };
  solid:inserts { ?person ex:givenName "Alex". };
  solid:deletes { ?person ex:givenName "Claudia". }.
```

### Response
#### Success Response (200 OK)
- The RDF resource is updated according to the patch.

#### Error Responses
- **422 Unprocessable Entity**: The patch document does not satisfy the N3 Patch constraints.
- **409 Conflict**: Conditions for the patch are not met (e.g., multiple mappings, required triples missing).

#### Response Example (Success)
(No specific response body defined for success, typically the updated resource or a confirmation.)

#### Response Example (422 Unprocessable Entity)
```json
{
  "error": "Unprocessable Entity",
  "message": "The provided N3 Patch document is invalid or does not conform to the required constraints."
}
```

#### Response Example (409 Conflict)
```json
{
  "error": "Conflict",
  "message": "The conditions specified in the patch could not be met."
}
```
```

--------------------------------

### URI Slash Semantics

Source: https://solidproject.org/TR/protocol/index

Explains the meaning of the slash character in URIs within the Solid Protocol, signifying hierarchical relationships and container resources.

```APIDOC
## URI Slash Semantics

### Description
The slash (`/`) character in the URI path indicates hierarchical relationship segments, and enables relative referencing [RFC3986]. The semantics of the slash character is shared by servers and clients. Paths ending with a slash denote a container resource.

If two URIs differ only in the trailing slash, and the server has associated a resource with one of them, then the other URI MUST NOT correspond to another resource. Instead, the server MAY respond to requests for the latter URI with a 301 redirect to the former. Servers MUST authorize prior to this optional redirect.
```
Tokens:
Raw