Skip to content
Snippets Groups Projects

WIP: Retribute Profiles Spec, initial draft

Open WIP: Retribute Profiles Spec, initial draft
profiles-spec into master
Open Agate requested to merge profiles-spec into master
Compare
and
1 file
+ 272
− 0
Compare changes
  • Side-by-side
  • Inline
specs/retribute-profiles-format.md 0 → 100644
+ 272
− 0
# Retribute Profiles Specification
**This document is a draft**
## Abstract
Retribute is an effort to ease the act of supporting and financing creators. We plan to do so
by providing standard, open, simple and easy-to use tools to creators and contributors, to automate
the most tedious tasks: finding who to support, where, how, how much, etc.
Retribute needs to be compatible with the widest possible range of existing applications and services. This is a strict requirement, as the project can only get traction and adoption if it's widely supported.
To ease the adoption process and ensure a consistent and stable ecosystem, Retribute involves a set of lightweight standards. The second one is the Retribute Profiles specification, described in the current document.
The goal of this specification is to describe the content, structure and format of the data required from creators
to be compatible with Retribute. A document that contains this kind of data is called a Retribute profile.
## Glossary
**Creator**
A person providing a content, piece of work or service to an audience.
Examples:
- a blog writer
- a music band
- a person posting nude pictures on social media
- a game developper
- a newspaper
- an organization developping free and open-source software
- an individual operating and maintaining online services for their community
**Contribution platforms**
Places advertised by creators to receive donations and other support expressions from their community.
Those platforms can be operated by a third-party (e.g a PayPal, Patreon, Liberapay or bank account) but also by
the creators themselves (e.g a cryptocurrency wallet, a postal address to receive checks, etc.).
**Retribute client**
Retribute clients are operated and used by contributors to automate the work of sending contributions to important creators in their life.
To do so, those clients provide suggestions, based on user configuration and historical data gathered from the content platforms where contributors are active.
## Design principles
The current document describes how Retribute profiles are structured and discovered. While Retribute clients can retrieve
and parse those profiles directly, it is also possible those profiles are fetched and cached by a separate service to
minimize network traffic.
**Simplicity**
Because Retribute profiles are intended to be produced by a wide range of providers, as well as by individuals and organizations, the format must be easy to read, understand, and low-footprint to produce and maintain.
**Backward compatibility**
We can't expect each individual creator to setup and maintain a Retribute profile. To ensure the barrier to entry
is as low as it can be, special care is given to ensure we can build Retribute profiles from existing, non-Retribute documents, and that existing Retribute profiles won't break as the specification evolves.
**Decentralization**
Retribute is a _decentralized_ effort, meaning we avoid to introduce single points of failure and control. This specification
makes no exception, and ensures creators don't have to rely on a third party to maintain and publish their profile, unless they choose to.
## Simple use-case
Alysha is a musican. While she's making her work available for free, on YouTube, SoundCloud and BandCamp, she'd like to get financial support to pursue this activity.
She opens a Patreon and a PayPal account to start receiving donations, and create a dedicated `/donate` page on her blog to explain
how much she needs, with a link redirecting to her Patreon and PayPal pages. She also adds a link to her BandCamp page, since
people can purchase her albums here.
On the various platforms where she publish her works, she includes a link to the `/donate` page on her blog, typically in the bio or website fields of her profile.
## What is a Retribute profile
A Retribute profile is a document that contains information and links to support a creator. Such profiles must contain at least one valid link to a contribution platform. Retribute profiles come in two flavours:
1. Implicit: those profiles aren't initally designed for Retribute, but can be parsed and converted to valid Retribute profiles
2. Explicit: those profiles are written from the ground up using our vocabulary
Profiles are typically HTML documents, but internally, all clients and and consumers should convert these to a JSON document.
### Implicit profile
Here is a simple Retribute profile, served as a HTML document on `https://alice.blog/donate`:
```html
<html>
<head>
<title>Support my work</title>
</head>
<body>
<p>If you like my music, please consider supporting me on the following platforms:</p>
<ul>
<li><a href="https://alice.bandcamp.com">Bandcamp</a></li>
<li><a href="https://paypal.me/@alice">Paypal</a></li>
</ul>
</body>
</html>
```
A consumer would parse this implicit profile to the following JSON document:
```json
{
"id": "https://alice.blog/donate",
"version": "0.1",
"title": "Support my work",
"means": [
{
"provider": "bandcamp",
"id": "alice",
"url": "https://alice.bandcamp.com",
"weight": 1,
},
{
"provider": "paypal",
"id": "alice",
"url": "https://paypal.me/@alice",
"weight": 1,
},
]
}
```
And that's pretty much it.
### Explicit profile (with HTML microdata)
Implicit profiles allows for backward compatibility with existing HTML documents, however, it's not possible to encode
more complex Retribute features in these. Since clients have to guess what are valid support means, it's could also yield to unwanted behaviour such as:
- Valid support means not being parsed
- Undesired valid means being parsed
To make the job of consumers easier and avoid unwanted side effects, Retribute profiles should be written using explicit markup.
This is done using [Microdata](https://html.spec.whatwg.org/multipage/microdata.html), embedded in our HTML. If we update the implicit example to use explicit microdata, we get the following:
```html
<html>
<head>
<title>Support my work</title>
</head>
<body itemscope itemtype="https://ns.retribute.me/v0.1/profile">
<h1 itemprop="title">Support my work</h1>
<p>If you like my music, please consider supporting me on the following platforms:</p>
<ul>
<li itemscope itemtype="https://ns.retribute.me/v0.1/mean">
<a itemprop="url" href="https://alice.bandcamp.com">
<data itemprop="id" value="alice"></data>
<span itemprop="provider" itemvalue="bandcamp">Bandcamp</span>
</a>
</li>
<li itemscope itemtype="https://ns.retribute.me/v0.1/mean">
<a itemprop="url" href="https://paypal.me/@alice">
<data itemprop="id" value="alice"></data>
<span itemprop="provider" itemvalue="paypal">Paypal</span>
</a>
</li>
</ul>
</body>
</html>
```
When parsed by a Retribute consumer, this HTML would result in the same JSON profile.
### Explicit profile (with JSON data)
Depending on the tool used to generate the website HTML, it may not be practical to embed microdata in the HTML markup.
As a result, Retribute Profiles can also be expressed directly as JSON documents, as shown below:
```html
<html>
<head>
<title>Support my work</title>
</head>
<script type="application/retribute+json">
{
"id": "https://alice.blog/donate",
"version": "0.1",
"title": "Support my work",
"means": [
{
"provider": "bandcamp",
"id": "alice",
"url": "https://alice.bandcamp.com",
"weight": 1,
},
{
"provider": "paypal",
"id": "alice",
"url": "https://paypal.me/@alice",
"weight": 1,
},
]
}
</script>
<body>
<p>If you like my music, please consider supporting me on the following platforms:</p>
<ul>
<li><a href="https://alice.bandcamp.com">Bandcamp</a></li>
<li><a href="https://paypal.me/@alice">Paypal</a></li>
</ul>
</body>
</html>
```
This alternate version leaves the HTML markup untouched.
### Profile contents
**todo**
## Redirections
An HTML document can reference a Retribute profile located at a different URI to indicate to a consumer what Retribute
information to use. This is done via a `<meta>` tag. If we reuse our previous set of exemples, Alice has setup a donation page
at `https://alice.blog/donate`. However, she prefer linking to the root of her blog (`https://alice.blog/`) whenever possible.
To ensure this doesn't break Retribute consumers, she adds the following `<meta>` tag in the HTML document served at `https://alice.blog/`:
```html
<html>
<head>
<meta name="retribute" content="https://alice.blog/donate"/>
</head>
</html>
```
A Retribute consumer can leverage this information to follow the redirection and Retrieve the corresponding profile.
## Profile discovery
In the use cases we want to support, Retribute clients need to bind suggestions in suggestions feeds to the corresponding
Retribute profiles in order to display the donation links.
However, the applications that produce these suggestions feeds do not necessarily know if the creator associated with a
piece of content has a Retribute profile, or where it is located.
To address this, we need to standardize and document the discovery process of Retribute profiles as well of the profile structure and contents.
A typical scenario, a Retribute client will pull one or more suggestion feeds. Suggestions feeds contain a list of creators
the user may want to support, and, for each of them, a list of identities, such as:
```json
{
"ids": [
"twitter:alice",
"web:https://alice.blog",
"activitypub:https://fediverse.social/users/alice"
]
}
```
(note that [the Suggestions Feed specification](https://dev.funkwhale.audio/retribute.me/spec/merge_requests/1) is still a draft and may evolve)
These ids are fundamental for the discovery process. A Retribute client use them to crawl identities related to a suggestions until it obtains a Retribute profile.
If we reuse the previous JSON example, a typical consumer willing to find Retribute information for this suggestion would follow these steps:
1. Loop over all the ids
2. Retrieve the HTML document at https://twitter.com/@alice
3. Find no Retribute profile in the HTML
4. Retrieve the HTML document at https://alice.blog
5. Find a `<meta name="retribute" content="https://alice.blog/donate"/>` tag in the HTML
6. Retrieve the HTML document at `https://alice.blog/donate`
7. Find a Retribute profile in the HTML (either explicit or implicit)