Solid-Storage-Link-Metadata

Living Document,

Issue Tracking:
GitHub
Editor:
Auke van Slooten (Muze)

CC0 To the extent possible under law, the editors have waived all copyright and related or neighboring rights to this work. In addition, as of 24 January 2022, the editors have made this specification available under the Open Web Foundation Agreement Version 1.0, which is available at http://www.openwebfoundation.org/legal/the-owf-1-0-agreements/owfa-1-0. Parts of this work may be from another specification document. If so, those parts are instead covered by the license of that specification document.

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.

1. Introduction

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.

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.

2. Definitions

server
A solid storage server, implementing this specification
client
A solid application that accesses the server.

3. Fetching and updating the correct auxiliary resource

To instruct a Solid Storage Server to redirect or delete a resource, you must fetch, change and upload the correct Auxiliary 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.

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.

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.

4. Link-Metadata predicates

4.1. 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:

@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.:

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

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

GET https://solid.storage.net/source
Assert: The server must respond with: 
HTTP/1.1 308 Moved Permanently
Location: http://www.example.com/

4.2. 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:

@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.:

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

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

GET https://solid.storage.net/source
Assert: The server must respond with: 
HTTP/1.1 307 Temporary Redirect
Location: http://www.example.com/

4.3. 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:

@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.:

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

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

GET https://solid.storage.net/source
Assert: The server must respond with: 
HTTP/1.1 404 Not Found

4.4. 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:

@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.:

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

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

GET https://solid.storage.net/source
Assert: The server must respond with: 
HTTP/1.1 410 Gone

5. 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.

6. Redirection and/or deletion of 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:

@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.:

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

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

GET https://solid.storage.net/source/child/resource
Assert: The server must respond with: 
HTTP/1.1 308 Moved Permanently
Location: http://www.example.com/child/resource

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.

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.

References

Normative References

[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc2119