Post Type Discovery

W3C Editor's Draft

This version:
http://ptd.spec.indieweb.org/
Latest published version:
https://www.w3.org/TR/post-type-discovery/
Latest editor's draft:
http://ptd.spec.indieweb.org/
Editor:
Tantek Çelik
Repository:
Github
Issues
Commits

Abstract

This section is non-normative.

Post Type Discovery specifies algorithms for determining the type of a post by what properties it has and potentially what value(s) they have, which helps avoid the need for explicit post types that are being abandoned by modern post creation UIs.

The Response Type Algorithm in particular specifies how a [Webmention] receiver determines whether a webmention is a comment, like, repost, RSVP, or other type of mention, widely implemented in practice by Webmention receivers to determine when and how to display various peer-to-peer social responses.

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

This specification was contributed to the W3C from the IndieWeb community and was one of several related specifications being produced by the Social Web Working Group. Now published as a W3C Note, the Post Type Discovery living specification is maintained at ptd.spec.indieweb.org. More history and evolution of Post Type Discovery can be found on the IndieWeb wiki.

This document was published by the Social Web Working Group as an Editor's Draft. Comments regarding this document are welcome. Please send them to public-socialweb@w3.org (subscribe, archives).

Publication as an Editor's Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 1 March 2017 W3C Process Document.

1. Introduction

This section is non-normative.

Post type discovery defines explicit algorithms for inferring the type of a post from other properties of that post.

Inferring the type of a post helps provide a bridge between formats and protocols without explicit post types (e.g. [h-entry], [jf2], [micropub], Atom ([RFC4287]), [RSS-2.0]) to those with explicit post types (e.g. [ActivityPub], [AS2]). For more details on those specifications see references, and for how they relate, see the overview document [social-web-protocols]. Post type discovery can apply to any post data structure independent of serialization (e.g. HTML, JSON, etc.)

2. Use Cases

This section is non-normative.

Both creation user interfaces, and post presentation designs are evolving to directly use the presence or absence of specific properties (and their values) directly, rather than depending on any kind of explicit "post type", thus why bother discovering a post type in the first place? This section documents the (few) use-case(s) that is/are known to date.

2.1 Synthesizing explicit type formats

There are existing formats that require explicit post types (e.g. ActivityStreams [AS1]), or are based on explicit post types, (e.g. ActivityStreams2 [AS2]), and code that consumes them expects explicit post types. Post type discovery enabling automatic synthesizing of such formats from posts that merely have a set of content related properties.

2.2 Aggregating responses by type

Modern social web posting systems implement multiple types of responses and provide user interfaces that show aggregate counts or collections of those responses grouped by type, e.g. number of likes, reposts, replies.

2.3 Notifications wording and filtering

Many social web implementations provide notifications to a user with response type specific wording, e.g. "Alice commented on your photo", "7 people liked your video". Automatically generating both the specific wording of these notifications, and deciding which to provide to the user, based on preferences and/or filtering, requires determining the specific response type.

3. Conformance

3.1 Conformance Keywords

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words "MAY", "MUST", "MUST NOT", "OPTIONAL", "RECOMMENDED", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", and "SHOULD NOT" are to be interpreted as described in [RFC2119].

3.2 Conformance Classes

There are many possible ways a Post Type Discovery implementation can be used and tested. This section describes possible conformance classes from existing implementations and use-cases.

3.2.1 Type Discovery Function

A Type Discovery Function consumes untyped posts from a possibly untyped format or protocol, (e.g. the h-entry microformat) and outputs the type output (e.g. a simple one-word string like "note" or "article") of the algorithm implemented (either the Response Type Algorithm or the Post Type Algorithm).

3.2.2 AS2 Proxy

An AS2 Proxy consumes untyped posts from an untyped format or protocol, and outputs valid [AS2] JSON using the equivalent AS2 Activity and/or Object Types.

4. Response Type Algorithm

The Response Type Algorithm ("the response algorithm") is for specifically discovering the type of a response, in particular as a result of receiving a [Webmention], by analyzing the "source" from the Webmention, called the "response" in the response algorithm. It is a proper subset of the general Post Type Algorithm (defined below).

Quoted property names in the response algorithm are defined in [h-entry].

5. Post Type Algorithm

The Post Type Algorithm ("the algorithm") discovers the type of a post given a data structure representing an item with a flat set of properties (e.g. JSON output from [microformats2-parsing]), each with one or more values, by following these steps until reaching the first "it is a(n) ... post" statement at which point the "..." is the discovered post type.

Quoted property names in the algorithm are defined in [h-entry].

Note

Note: for [RFC4287], use the Atom entry title for the "name" property, and the Atom entry content for the content as mentioned in the algorithm.

Note

Note: for [RSS-2.0], use the RSS item title for the "name" property, and the RSS item description for the content as mentioned in the algorithm.

6. Post Types Table

The following table documents the conversion from the output of the algorithms to [AS2] equivalents.

Post Type AS2 equivalent
event Event
rsvp Event RSVP
repost Announce
like Like
reply Note with inReplyTo
video Video
photo Image
note Note
article Article

7. Methodology

This section is non-normative.

There are two important aspects to the methodology of the Post Type Discovery algorithm: scope (why is something explicitly in the algorithm), and order (why is something where it is in the algorithm).

7.1 Scope

The algorithm could attempt to cover innumerable potential hypothetical post types, or take an evidence based approach, focusing on real world publishing practices. This specification does the latter, specifically by placing a minimum bar of documented real world publishing practices of different visually apparent post types on the open web at recent (< 1 year old) permalinks, each with at least three independent implementations that have converged on what properties (and potentially values thereof) they have to imply their visually apparent post types. As a result of being evidence based, it is likely this specification will expand over time as more apparent post types are published by more convergent implementations.

7.2 Order

The algorithm must also specify an order (e.g. of precedence) that various properties (and their values) imply various post types. The algorithm is ordered by post types that are in general "richer" in terms of content as well as show greater cognitive effort by the author.

8. Other Types To Consider

This section is non-normative.

Other types may be included in future iterations of the algorithms based on convergence of publishing patterns and critical mass of adoption thereof.

See: IndieWeb wiki: Kinds of Posts for a list of additional possible post types that have growing adoption.

9. Examples

This section is non-normative.

9.1 Like Post

Here is an example [h-entry] post from Activity Streams 2.0 Vocabulary examples [AS2-vocab]:

<div class="h-entry p-name">
  <span class="p-author h-card">Sally</span>
  liked
  <a class="u-like-of"
    href="http://example.org/notes/1">
    http://example.org/notes/1
  </a>
</div>

Following the algorithm, the step "If the post has a "like-of" property with a valid URL" is satisfied and thus the algorithm returns that the post is a "like" post.

Given this semantic, an implementation can generate (or process as if generated and consumed) the following AS2 JSON, in particular the "@type": "Like" in this output is what is determined by this algorithm:

{
  "@type": "Like",
  "actor": {
    "@type": "Person",
    "displayName": "Sally"
  },
  "object": "http://example.org/notes/1"
} 

10. FAQ

This section is non-normative.

10.1 What about a photo reply

Q: What about a reply that includes a photo?

A: It's a reply.

Q2: Should that show up as a "photo" post?

A2: It should show up as a "reply" and not be in a user's published feed of their photos. The user-centric design here is to treat replies separately, because in practice, when users post replies to others' posts, and include a photo, the photos typically assume the context of that other post, and would look odd outside of it (e.g. in a generic "photos" feed). In addition, by not including reply photos in a user's feed of their photos, it gives the user the freedom to reply to other posts with whatever they wish, including photos, and not have those reply-specific photos pollute their streams of "their stuff" that their followers subscribe to.

A2a: From a presentation perspective, a reply should primarily be displayed as a reply first, and then adapt accordingly to whatever other properties it may have.

10.2 Is a video tag sufficient

Q: Is a video tag sufficient to imply a video post?

A: No, video tags can be used for additional content e.g. inside an article. Only relying on video tag markup would lead to false positives.

11. Implementations

This section is non-normative.

Implementations, in progress, partial, or complete, of Post Type Discovery.

11.1 Granary

Granary synthesizes ActivityStreams [AS1], [microformats2], and Atom [RFC4287] from various input feeds and sources, and as such has some code that can be considered in progress or even a partial implementation of Post Type Discovery:

11.2 p3k

p3k (a CMS) implements Post Type Discovery internally within its [micropub] endpoint to automatically add posts to various collections. E.g.: if this post is a reply, it goes in the "replies" collection. if it's an RSVP, it goes in the "rsvps" and "replies" collections.

11.3 mf2util

mf2util exposes a function for post_type_discovery that takes an h-entry and returns "like", "reply", "note", "article", etc.

A. Change Log

This section is non-normative.

A.1 Changes from 1 August 2017 WD to this version

A.2 Changes from 14 June 2017 WD to 1 August 2017 WD

A.3 Changes from 1 March 2017 WD to 14 June 2017 WD

A.4 Changes from 28 October 2016 WD to 1 March 2017 WD

B. References

B.1 Normative references

[AS2]
Activity Streams 2.0. J. Snell; E. Prodromou. https://www.w3.org/. Candidate Recommendation. URL: https://www.w3.org/TR/activitystreams-core/
[h-entry]
h-entry. Tantek Çelik. http://microformats.org. Living Specification. URL: http://microformats.org/wiki/h-entry
[h-event]
h-event. Tantek Çelik. http://microformats.org. Living Specification. URL: http://microformats.org/wiki/h-event
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[Webmention]
Webmention. Aaron Parecki. W3C. 12 January 2017. W3C Recommendation. URL: https://www.w3.org/TR/webmention/

B.2 Informative references

[ActivityPub]
ActivityPub. Christopher Webber; Jessica Tallon. W3C. 5 December 2017. W3C Proposed Recommendation. URL: https://www.w3.org/TR/activitypub/
[AS1]
JSON Activity Streams 1.0. J. Snell; M. Atkins; W. Norris; C. Messina; M. Wilkinson; R. Dolin. http://activitystrea.ms. unofficial. URL: http://activitystrea.ms/specs/json/1.0/
[AS2-vocab]
Activity Vocabulary. J. Snell; E. Prodromou. https://www.w3.org/. Candidate Recommendation. URL: http://www.w3.org/TR/activitystreams-vocabulary
[jf2]
JF2 Post Serialization Format. Benjamin Roberts. W3C. 10 January 2018. W3C Note. URL: https://www.w3.org/TR/jf2/
[microformats2]
Microformats2. Tantek Çelik. http://microformats.org. Living Specification. URL: http://microformats.org/wiki/microformats2
[microformats2-parsing]
Microformats2 Parsing. Tantek Çelik. http://microformats.org. Living Specification. URL: http://microformats.org/wiki/microformats2-parsing
[micropub]
Micropub. Aaron Parecki. W3C. 23 May 2017. W3C Recommendation. URL: https://www.w3.org/TR/micropub/
[RFC4287]
The Atom Syndication Format. M. Nottingham, Ed.; R. Sayre, Ed.. IETF. December 2005. Proposed Standard. URL: https://tools.ietf.org/html/rfc4287
[RSS-2.0]
RSS 2.0. Dave Winer. RSS Board. Stable. URL: http://www.rssboard.org/rss-specification
[social-web-protocols]
Social Web Protocols. Amy Guy. W3C. 25 December 2017. W3C Note. URL: https://www.w3.org/TR/social-web-protocols/