From 9182fc84de95646109fae36b2c0ba49130be458c Mon Sep 17 00:00:00 2001 From: Evan Prodromou Date: Fri, 15 Nov 2024 15:34:23 -0500 Subject: [PATCH] feat: reorganize author discovery --- index.html | 243 ++++++++++++++++++++++++++++++++--------------------- 1 file changed, 146 insertions(+), 97 deletions(-) diff --git a/index.html b/index.html index 021521c..05c35a0 100644 --- a/index.html +++ b/index.html @@ -787,7 +787,7 @@

Discover equivalent object

Each of these properties can have values that are a string, a JSON object, or a JSON array consisting of strings and/or JSON objects. If the value is a string, it is the URL of the author object. If the value is an object, its id property is the URL of the ActivityPub JSON-LD object. For an array, each item can be resolved as either a string or an object.

The advantage of this method is that it does not require a separate discovery path for authors.

-

Example

+

Example

Given an HTML page at https://html.example/note-1.html that represents a Note object, the consumer can use an HTML <link> header to identify the URL of the ActivityPub note:

           <link
@@ -814,133 +814,182 @@ 
Example
-

Object discovery failure

+

Object discovery failure

This discovery method can fail if the ActivityPub object requires authentication to be fetched -- which is often the case for content that was not made available to the public by the author. A simple consumer may not have the context necessary to use OAuth 2.0, HTTP Signature, or other authentication methods.

Not all ActivityPub implementations include the attributedTo or actor property for an object in its default representation.

-

HTTP Link header

-

The Link header can also be used to identify the author of an HTML page. The author link type identifies the author of a resource. So, a Link header with a rel property equal to "author" and a type property equal to "application/activity+json" will link to the ActivityPub representation of the author of the object.

-

This technique has the advantage of requiring a minimum amount of data transfer and complicated parsing of data structures. It can also be used with different media types than just HTML; for example, a JPEG image.

-
-

Example

-

- Given an HTML page at https://html.example/files/video-33.html that represents a Video object, the consumer can use an HTTP HEAD request to identify the URL of the ActivityPub video: -

- 
-          HEAD /files/video-33.html HTTP/1.1
-          Host: html.example
-
-

The publisher would respond with the HTTP headers:

- 
-          HTTP/1.1 200 OK
-          Content-Type: text/html
-          Link: <https://ap.example/api/videos/video-33.jsonld>; rel="alternate"; type="application/activity+json"
-          Link: <https://ap.example/profiles/person-7.jsonld>; rel="author"; type="application/activity+json"
-
-

Note that there are two Link headers in the result; one represents the Video, and the other represents the Person that authored the video. The rel value of "author" distinguishes the author link.

-
+

URL as input

+

This section describes techniques for discovering an ActivityPub author object using the HTML representation's URL as an input. The HTML representation's URL may come from ActivityPub properties, links in other content, or by other means.

+

If these techniques do not succeed, consumers can fetch the content of the HTML document and use one of the techniques that require HTML as input.

-

Link header failure

-

Some non-compliant publishers will respond to a HEAD request with the full body of the HTML document.

+

HTTP Link header

+

The Link header can also be used to identify the author of an HTML page. The author link type identifies the author of a resource. So, a Link header with a rel property equal to "author" and a type property equal to "application/activity+json" will link to the ActivityPub representation of the author of the object.

+

This technique has the advantage of requiring a minimum amount of data transfer and complicated parsing of data structures. It can also be used with different media types than just HTML; for example, a JPEG image.

+
+
Example
+

+ Given an HTML page at https://html.example/files/video-33.html that represents a Video object, the consumer can use an HTTP HEAD request to identify the URL of the ActivityPub video: +

+ 
+            HEAD /files/video-33.html HTTP/1.1
+            Host: html.example
+
+

The publisher would respond with the HTTP headers:

+ 
+            HTTP/1.1 200 OK
+            Content-Type: text/html
+            Link: <https://ap.example/api/videos/video-33.jsonld>; rel="alternate"; type="application/activity+json"
+            Link: <https://ap.example/profiles/person-7.jsonld>; rel="author"; type="application/activity+json"
+
+

Note that there are two Link headers in the result; one represents the Video, and the other represents the Person that authored the video. The rel value of "author" distinguishes the author link.

+
+
+
Link header failure
+

Some non-compliant publishers will respond to a HEAD request with the full body of the HTML document.

+
-

HTML <link> element

-

The ActivityPub id of the author of an object represented by an HTML document can also be found using the HTML <link> element. As with the HTTP Link header, if a <link> element has a rel attribute equal to "author" and a type attribute equal to "application/activity+json", its href property is the URL of the ActivityPub object representing the author.

-

This technique is useful when the HTML page is already downloaded and available, such as within a browser environment.

-
-

Example

-

Given an HTML page at https://html.example/files/document-40.html that represents a Document object, the consumer can use the following HTML to identify the URL of the ActivityPub representation of the document:

- 
-          <!doctype html>
-          <html>
-            <head>
-              <title>Document 33</title>
-              <link
-                rel="author"
-                type="application/activity+json"
-                href="https://ap.example/profiles/person-7.jsonld" />
-            </head>
-            <body>
-              <!-- rest of the page -->
-            </body>
-          </html>
-
-

In this example, the <link> element with the rel attribute set to "author" and the type attribute set to "application/activity+json" is the author of the document.

-
+

Document as input

+

These techniques require the contents of the HTML representation. This could already be available in a browser environment, or through other means.

+

If these techniques don't succeed, it's sometimes possible to obtain the URL of the document through the environment, for example, using the document.location property in a browser JavaScript program. Consumers can then try techniques that use the URL as input.

-

Link element failure

-

Some servers may include a <link> element with an author relation and with a JSON type or JSON-LD type that does not link to an ActivityPub resource.

+

HTML <link> element

+

The ActivityPub id of the author of an object represented by an HTML document can also be found using the HTML <link> element. As with the HTTP Link header, if a <link> element has a rel attribute equal to "author" and a type attribute equal to "application/activity+json", its href property is the URL of the ActivityPub object representing the author.

+

This technique is useful when the HTML page is already downloaded and available, such as within a browser environment.

+
+
Example
+

Given an HTML page at https://html.example/files/document-40.html that represents a Document object, the consumer can use the following HTML to identify the URL of the ActivityPub representation of the document:

+ 
+            <!doctype html>
+            <html>
+              <head>
+                <title>Document 33</title>
+                <link
+                  rel="author"
+                  type="application/activity+json"
+                  href="https://ap.example/profiles/person-7.jsonld" />
+              </head>
+              <body>
+                <!-- rest of the page -->
+              </body>
+            </html>
+
+

In this example, the <link> element with the rel attribute set to "author" and the type attribute set to "application/activity+json" is the author of the document.

+
+
+
Link element failure
+

Some servers may include a <link> element with an author relation and with a JSON type or JSON-LD type that does not link to an ActivityPub resource.

+
-
-
-

OpenGraph Protocol

-

- The OpenGraph Protocol is a set of metadata properties that can be included in an HTML document to provide information about the document. Several of these properties can be used to identify the author of the document; usually with the URL of an HTML page that has a profile type. -

- -

- For these properties, the most likely discovery path is to follow the property's URL value to an HTML page for the profile, and then use forward discovery to find the ActivityPub object corresponding to that profile. -

-

- Another option is the fediverse:creator property, developed by Mastodon. This property is used to identify the creator of a document. Its value is the Webfinger ID of the creator, prefixed with an @ character, not an acct: URL. The consumer can use the Webfinger protocol to find the ActivityPub object corresponding to the creator. -

-

The advantage of using OGP for metadata is that it is widely implemented by Web publishing systems.

-

Example

+

OpenGraph Protocol

- Given an HTML page at https://html.example/files/article-40.html that represents a Article object, the consumer can use the OpenGraph metadata to identify the URL of HTML profile for the author of the article: + The OpenGraph Protocol is a set of metadata properties that can be included in an HTML document to provide information about the document. Several of these properties can be used to identify the author of the document; usually with the URL of an HTML page that has a profile type.

- 
-          <!doctype html>
-          <html>
-            <head>
-              <title>Article 40</title>
-              <meta property="article:author" content="https://html.example/profiles/person-7.html" />
-            </head>
-            <body>
-              <!-- rest of the page -->
-            </body>
-          </html>
-
+
    +
  • music:musician identifies the creator of a song or album.
    • +
  • music:creator identifies the creator of a playlist or station.
    • +
  • video:actor identifies the actor in a video.
    • +
  • video:director identifies the director of a video.
    • +
  • video:writer identifies the writer of a video.
    • +
  • article:author identifies the author of an article.
    • +
  • book:author identifies the author of a book.
    • +

- In this example, the article:author property is the author of the document. + For these properties, the most likely discovery path is to follow the property's URL value to an HTML page for the profile, and then use forward discovery to find the ActivityPub object corresponding to that profile.

- Given an HTML page at https://html.example/files/video-40.html that represents a Video object, the consumer can use OpenGraph metadata to identify the Webfinger ID of the creator of the video: + Another option is the fediverse:creator property, developed by Mastodon. This property is used to identify the creator of a document. Its value is the Webfinger ID of the creator, prefixed with an @ character, not an acct: URL. The consumer can use the Webfinger protocol to find the ActivityPub object corresponding to the creator.

+

The advantage of using OGP for metadata is that it is widely implemented by Web publishing systems.

+
+
Example
+

+ Given an HTML page at https://html.example/files/article-40.html that represents a Article object, the consumer can use the OpenGraph metadata to identify the URL of HTML profile for the author of the article: +

+ 
+            <!doctype html>
+            <html>
+              <head>
+                <title>Article 40</title>
+                <meta property="article:author" content="https://html.example/profiles/person-7.html" />
+              </head>
+              <body>
+                <!-- rest of the page -->
+              </body>
+            </html>
+
+

+ In this example, the article:author property is the author of the document. +

+

+ Given an HTML page at https://html.example/files/video-40.html that represents a Video object, the consumer can use OpenGraph metadata to identify the Webfinger ID of the creator of the video: +

+ 
+            <!doctype html>
+            <html>
+              <head>
+                <title>Video 40</title>
+                <meta property="fediverse:creator" content="@person-22@ap.example" />
+              </head>
+              <body>
+                <!-- rest of the page -->
+              </body>
+            </html>
+
+

+ In this example, the fediverse:creator property is the Webfinger ID of the creator of the video, prefixed with the @ symbol. The Webfinger ID can be used to find the ActivityPub object corresponding to the creator. +

+
+
+
OpenGraph Protocol failure
+

+ The OpenGraph Protocol is not widely used for identifying authors of documents. When it is used, the profile page may not support discovery of an ActivityPub object. +

+
+
+
+
+

Discovering author HTML

+

Another option for author discovery is to discover the HTML profile page for the author of the resource, and then discover the equivalent ActivityPub object for the HTML profile page.

+

Techniques for discovering author HTML pages are out of scope for this report, but may include using HTTP Link headers, <link> elements, <a> elements, or Webfinger link objects with the rel property set to "author" and the type property set to "text/html" or omitted. Embedded JSON-LD, OpenGraph Protocol, and other mechanisms exist for discovering author profile HTML pages.

+
+

Example

+

Given the contents of an HTML page at https://html.example/files/video-40.html that represents a Video object, the consumer can check the <link> elements in the HTML to find the URL of the author's profile page:

           <!doctype html>
           <html>
             <head>
               <title>Video 40</title>
-              <meta property="fediverse:creator" content="@person-22@ap.example" />
+              <link
+                rel="author"
+                type="text/html"
+                href="https://html.example/profiles/person-22.html" />
             </head>
             <body>
               <!-- rest of the page -->
             </body>
           </html>
-

- In this example, the fediverse:creator property is the Webfinger ID of the creator of the video, prefixed with the @ symbol. The Webfinger ID can be used to find the ActivityPub object corresponding to the creator. -

+

It could then use a forward discovery technique, such as HTTP Link header discovery, to get the equivalent ActivityPub object.

+ 
+          HEAD /profiles/person-22.html HTTP/1.1
+          Host: html.example
+
+

The response might include a Link header with the URL of the equivalent ActivityPub object:

+ 
+          HTTP/1.1 200 OK
+          Content-Type: text/html
+          Link: <https://ap.example/profiles/person-22.jsonld>; rel="alternate"; type="application/activity+json"
+
-

OpenGraph Protocol failure

-

- The OpenGraph Protocol is not widely used for identifying authors of documents. When it is used, the profile page may not support discovery of an ActivityPub object. -

-
+

Author HTML failure

+

Author HTML discovery can fail if the author's profile page is not available, or if the profile page does not link to an ActivityPub object.

+