Abstract

Post Type Discovery specifies an algorithm for determining the type of a post (related issue: #9: Use AS2 specific language for post types) 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.

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 is one of several related specifications being produced by the Social Web Working Group. 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 a Working Draft. This document is intended to become a W3C Recommendation. Comments regarding this document are welcome. Please send them to public-socialweb@w3.org (subscribe, archives).

Publication as a Working 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 5 February 2004 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 is an explicit algorithm for inferring the type of a post from other properties of that post.

Inferring the type of a post helps provide a bridge between systems without explicit post types (e.g. [h-entry], [jf2], [micropub]) to systems 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.)

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

1.2 Synthesizing explicit type formats

This section is non-normative.

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

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

4. Post Type Algorithm

The Post Type Algorithm ("the algorithm") discovers the type of a post given a data structure representing a post with a flat set of properties (e.g. Activity Streams (1.0 or 2.0) JSON, or 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].

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

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

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

6. Other Types Under Consideration

This section is non-normative.

Other types are being considered and will be included in the future iterations of the algorithm based on convergence of publishing patterns and critical mass of adoption thereof.

7. Examples

This section is non-normative.

7.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"
} 

8. FAQ

This section is non-normative.

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

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

9. Implementations

This section is non-normative.

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

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

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

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

Changes from 1 March 2017 WD to this version

Changes from 28 October 2016 WD to 1 March 2017 WD

B. References

B.1 Normative references

[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/
[h-entry]
h-entry. Tantek Çelik. http://microformats.org. Living Specification. URL: http://microformats.org/wiki/h-entry

B.2 Informative references

[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]
Activity Streams 2.0. J. Snell; E. Prodromou. https://www.w3.org/. Candidate Recommendation. URL: https://www.w3.org/TR/activitystreams-core/
[AS2-vocab]
Activity Vocabulary. J. Snell; E. Prodromou. https://www.w3.org/. Candidate Recommendation. URL: http://www.w3.org/TR/activitystreams-vocabulary
[ActivityPub]
ActivityPub. Christopher Webber; Jessica Tallon. W3C. 9 May 2017. W3C Candidate Recommendation. URL: https://www.w3.org/TR/activitypub/
[RFC4287]
The Atom Syndication Format. M. Nottingham, Ed.; R. Sayre, Ed.. IETF. December 2005. Proposed Standard. URL: https://tools.ietf.org/html/rfc4287
[jf2]
JF2 Post Serialization Format. Benjamin Roberts. W3C. 12 June 2017. W3C Working Draft. 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/
[social-web-protocols]
Social Web Protocols. Amy Guy. W3C. 4 May 2017. W3C Working Draft. URL: https://www.w3.org/TR/social-web-protocols/