index.bs

<pre class='metadata'>
Title: Solid-Storage-Link-Metadata
Boilerplate: issues-index no
Boilerplate: style-darkmode off
Shortname: solid-storage-lm
Level: 1
Repository: https://github.com/pdsinterop/solid-link-metadata
Markup Shorthands: markdown yes
Max ToC Depth: 2
Editor: [Auke van Slooten](https://github.com/poef) ([Muze](https://www.muze.nl/))
Status: LD
Abstract:
  When linked data resources are moved to another location, the chain of
  links is broken. Over time this will degrade the solid ecosystem. This
  document aims to address this by building on top of current web standards,
  to allow solid storage servers to be instructed to send redirect information.
Status Text:
  This section describes the status of this document at the time of its publication.

  This document was published by the [PDS Interop Group](https://pdsinterop.org)
  for review by the [Solid Commyinty Group](https://www.w3.org/community/solid/)
  as a preliminary draft. There has been no review yet, and the information
  in this document is subject to change. You are invited to
  [contribute](https://github.com/pdsinterop/solid-link-metadata/issues) any
  feedback, comments or questions you may have.
</pre>

# Introduction # {#intro}

This document outlines in detail how a Solid Application can instruct a Solid Storage Server to
send redirect (HTTP 307 or 308 status) or deleted (HTTP 404 or 410) responses
to requests for specific files, by adding link metadata triples to the [description resource](https://solidproject.org/TR/protocol#auxiliary-resources-description-resource).

In the remainder of this specification wherever you see the `.meta` filename referenced, it is assumed that this
is the filename and URL returned in the `Link` header in an earlier HTTP request to the parent folder of the resource
being manipulated.

# Definitions # {#definitions}

<dl>
<dt>server</dt>
<dd>A solid storage server, implementing this specification</dd>
<dt>client</dt>
<dd>A solid application that accesses the server.</dd>
</dl>

# Fetching and updating the correct auxiliary resource # {#lm-auxiliary-description-resource}

To instruct a Solid Storage Server to redirect or delete a resource,
you must fetch, change and upload the correct [Auxiliary Description 
Resource](https://solidproject.org/TR/protocol#auxiliary-resources-description-resource).

The correct description resource is the one returned in the `Link` header
on a HTTP request of the parent container that contains the resource
you want to redirect or delete.

<div class=example>
For example, to redirect this resource:
```
https://www.example.com/container/resource.html
```
The client must do a HTTP request, e.g. HEAD or GET, on the container:
```
HEAD https://www.example.com/container/
```
This will return response headers, among them this `Link` header:
```
Link: <https://www.example.com/container/.meta>; rel="describes"
```
So the client can instruct the server to redirect the original resource.html 
by adding link-metadata predicates to the resource at 
`https://www.example.com/container/.meta`. 
</div>

Note: In the remainder of this specification wherever you see the `.meta` 
filename referenced, it is assumed that this is the filename and URL returned 
in the `Link` header in an earlier HTTP request to the parent folder of the 
resource being manipulated, according to the rules outlined above.


# Link-Metadata predicates # {#lm-predicates}

## lm:redirectPermanent ## {#lm-redirectPermanent}

This predicate is used to instruct a server to send a 
HTTP 308 Permanently Redirected response to a request. Here is an 
example `.meta` description resource:

```turtle
@prefix lm: <https://purl.org/pdsinterop/link-metadata#> .
@prefix local: <./> .

local:source lm:redirectPermanent <https://www.example.com/> .
```

If the client uploads this to a server, e.g.:

```http
PUT https://solid.storage.net/.meta
```

Afterwards, when the client requests the `source` file from this server, like this:

```http
GET https://solid.storage.net/source
```

<div class=assertion>
Assert: The server must respond with:

```http
HTTP/1.1 308 Moved Permanently
Location: http://www.example.com/
```
</div>

## lm:redirectTemporary ## {#lm-redirectTemporary}

This predicate is used to instruct a server to send a 
HTTP 307 Temporary Redirect response to a request. Here is an example 
`.meta` description resource:

```turtle
@prefix lm: <https://purl.org/pdsinterop/link-metadata#> .
@prefix local: <./> .

local:source lm:redirectTemporary <https://www.example.com/> .
```

If the client uploads this to a server, e.g.:

```http
PUT https://solid.storage.net/.meta
```

Afterwards, when the client requests the `source` file from this server, like this:

```http
GET https://solid.storage.net/source
```

<div class=assertion>
Assert: The server must respond with:

```http
HTTP/1.1 307 Temporary Redirect
Location: http://www.example.com/
```
</div>

## lm:deleted ## {#lm-deleted}

This predicate is used to instruct a Solid Storage Server to send a 
HTTP 404 Not Found response to a request. Here is an example `.meta` description resource:

```turtle
@prefix lm: <https://purl.org/pdsinterop/link-metadata#> .
@prefix local: <./> .

local:source lm:deleted "Reason" .
```

If the client uploads this to a Solid Storage Server, e.g.:

```http
PUT https://solid.storage.net/.meta
```

Afterwards, when the client requests the `source` file from this server, like this:

```http
GET https://solid.storage.net/source
```

<div class=assertion>
Assert: The server must respond with:

```http
HTTP/1.1 404 Not Found
```
</div>

## lm:forget ## {#lm-forget}

This predicate is used to instruct a server to send a 
HTTP 410 Gone response to a request. Here is an example `.meta` 
description resource:

```turtle
@prefix lm: <https://purl.org/pdsinterop/link-metadata#> .
@prefix local: <./> .

local:source lm:forget "Reason" .
```

If the client uploads this to a server, e.g.:

```http
PUT https://solid.storage.net/.meta
```

Afterwards, when the client requests the `source` file from this server, like this:

```http
GET https://solid.storage.net/source
```

<div class=assertion>
Assert: The server must respond with:

```http
HTTP/1.1 410 Gone
```
</div>

# Last Write Wins # {#last-write-wins}

When a `.meta` description resource is uploaded to a server, the link-metadata triples
inside it override any existing files or directories. If file `source` exists, but the `.meta` file 
instructs the server to redirect it, or delete/forget it, any subsequent requests for that file should 
be handled according to these instructions.

The exception is when the server receives a `PUT` request for that file. In that case, the file should 
be received and stored as normal. Any link metadata redirect, delete or forget triple with that file 
as subject, must be automatically removed by the server.

Subsequent requests will than be handled as normal.

# Redirection and/or deletion of folders # {#folders}

When a `.meta` description resource instructs a server to redirect or 
delete (or forget) a folder, all requests for resources contained in that folder
must also be handled as redirected or deleted. Take this `.meta` description resource:

```turtle
@prefix lm: <https://purl.org/pdsinterop/link-metadata#> .
@prefix local: <./> .

local:source lm:redirectPermanent <https://www.example.com/> .
```

If the client uploads this to a server, e.g.:

```http
PUT https://solid.storage.net/.meta
```

Afterwards, when the client requests any resource contained within 
the `source/` folder from this server, e.g.:

```http
GET https://solid.storage.net/source/child/resource
```

<div class=assertion>
Assert: The server must respond with:

```http
HTTP/1.1 308 Moved Permanently
Location: http://www.example.com/child/resource
```
</div>

Assert: The server must not check if the redirected resource is/was a folder.

Assert: The server must not check if the requested resource exists locally.

Assert: The server must ignore any earlier instructions in a `.meta` resource on child resources.