Defining the Retrieval Format for Webmentions

[jalcine]

Currently, the Webmention spec focuses solely on how to send and receive webmentions. Other than verification, update and delete behaviour, it leaves the details of retrieval, storage and presentation up to the implementor's discretion.

The most common use-case for webmentions is to notify a post (an HTML page with h-entry markup) or person (ditto with h-card) that another post has responded to it somehow, where the response could be a plain mention, a reply, a repost, a like, etc. Sites which receive such reply webmentions typically fetch the reply, parse it for h-entry markup, store it locally and present reactions to the post alongside it.

Because the process of verifying, parsing, fetching, sanitizing, re-formatting, organising and presenting external content is challenging (or simply not possible on static sites), and no implementation guide exists, many people rely on external services to handle incoming webmentions and present lists of reactions. Popular examples of external webmention handlers include https://webmention.io and http://mention.tech/

It may be useful to define discovery and formats which external webmention handlers use, to enable consuming software to use any such provider, and to enable people to switch providers or use multiple providers more easily.

• What kind of information should one expect when requesting a set of Webmentions from a endpoint/service/provider?
• Should it be only one format or should some sort of content negotiation occur?

---

This issue came out of a discussion from Webmentions beyond Webmention.io and therefore has a slight bias about how one could attempt to normalize or implement output similar to https://webmention.io

[jalcine]

For context, https://webmention.io's responses for my personal site looks something like (truncated for brevity):

Example JF2-esque output

{
  "type": "feed",
  "name": "Webmentions",
  "children": [
    {
      "type": "entry",
      "author": {
        "type": "card",
        "name": "Jamie Tanna",
        "photo": "https://webmention.io/avatar/www.jvt.me/1a30a04da8e03ed78b17bd01777f3892c95de2a05f974eaa739b858aaa1749d4.png",
        "url": "https://www.jvt.me"
      },
      "url": "https://www.jvt.me/posts/2020/05/13/render-micropub-client-data/",
      "published": "2020-05-13T13:42:33+01:00",
      "wm-received": "2020-05-13T13:06:52Z",
      "wm-id": 795649,
      "wm-source": "https://www.jvt.me/posts/2020/05/13/render-micropub-client-data/",
      "wm-target": "https://jacky.wtf",
      "name": "Rendering Micropub Client Data on Posts",
      "syndication": [
        "https://news.indieweb.org/en",
        "https://indieweb.xyz/en/indieweb",
        "https://indieweb.xyz/en/microformats"
      ],
      "summary": {
        "content-type": "text/plain",
        "value": "Sharing more information about Micropub clients that have created a post, if possible."
      },
      "content": {
        "html": "<p>Aside from <a href=\"https://www.jvt.me/kind/articles/\">blog posts</a>, like this one, content I publish to my site is using the <a href=\"https://www.w3.org/TR/micropub/\">open standard Micropub</a>, which I've supported <a href=\"https://www.jvt.me/posts/2019/08/26/setting-up-micropub/\">since last August</a>.</p><p>Being an open standard means there are lots of client implementations, so I'm free to use various different Web/mobile apps to interact with my site.</p><p>When I set this up, I did something I quite like, which is to make it so any new content created contains details of which Micropub client created it (the <code>client_id</code>).</p><p>Up until now, I've been showing this <code>client_id</code>, which is a URL such as <code>https://indigenous.realize.be</code>, but that may not be super meaningful to the reader.</p><p>A while back, I noticed that <span class=\"h-card\"><a class=\"u-url p-name\" href=\"https://jacky.wtf\">Jacky</a></span> has some nice rendering of which client published - you can see an example <a href=\"https://v2.jacky.wtf//post/1f8ffba0-e948-4dac-aa6a-3975074cced9\">on this note</a> for the same client mentioned above, Indigenous.</p><p>If you've visited my site since last night, you may notice that I'm also starting to do this now:</p><ul><li><a href=\"https://www.jvt.me/mf2/2020/05/3dpma/\">example with a logo</a></li>\n<li><a href=\"https://www.jvt.me/mf2/2020/05/np6jk/\">example without a logo</a></li>\n<li><a href=\"https://www.jvt.me/mf2/2020/05/4zeet/\">example with no client information</a></li>\n</ul><p>I'm hoping that this may make it slightly nicer to the reader, although I'm wondering if there's anything I can do to make it better.</p><p>So how am I discovering this client metadata?</p><p><a href=\"https://indieauth.spec.indieweb.org/#application-information\">IndieAuth defines the <code>h-app</code> markup</a> using <a href=\"https://microformats.io\">Microformats2</a> for this purpose, which is great! It is optional for clients, which means I have to still make it possible for a client not to provide it, but for those that do, it so far contains all the information I need to make the metadata more useful.</p><p>I've decided to make this a manual process to update the metadata, for now, so I'm not making my site's build reliant on the services to be available so I can retrieve their metadata.</p>",
        "text": "Aside from blog posts, like this one, content I publish to my site is using the open standard Micropub, which I've supported since last August.Being an open standard means there are lots of client implementations, so I'm free to use various different Web/mobile apps to interact with my site.When I set this up, I did something I quite like, which is to make it so any new content created contains details of which Micropub client created it (the client_id).Up until now, I've been showing this client_id, which is a URL such as https://indigenous.realize.be, but that may not be super meaningful to the reader.A while back, I noticed that Jacky has some nice rendering of which client published - you can see an example on this note for the same client mentioned above, Indigenous.If you've visited my site since last night, you may notice that I'm also starting to do this now:example with a logo\nexample without a logo\nexample with no client information\nI'm hoping that this may make it slightly nicer to the reader, although I'm wondering if there's anything I can do to make it better.So how am I discovering this client metadata?IndieAuth defines the h-app markup using Microformats2 for this purpose, which is great! It is optional for clients, which means I have to still make it possible for a client not to provide it, but for those that do, it so far contains all the information I need to make the metadata more useful.I've decided to make this a manual process to update the metadata, for now, so I'm not making my site's build reliant on the services to be available so I can retrieve their metadata."
      },
      "mention-of": "https://jacky.wtf",
      "wm-property": "mention-of",
      "wm-private": false,
      "rels": {
        "canonical": "https://www.jvt.me/posts/2020/05/13/render-micropub-client-data/"
      }
    }
 }

[manton]

Here's an example of JF2 from Micro.blog where I was attempting to copy Webmention.io. It has a format parameter and also supports returning JSON Feed (or actual JavaScript to block the page and output HTML directly, but that may be better handled when we talk about "rendering").

I like the earlier suggestion of considering something closer to Microsub, too, since presumably that could get us consistent paging. Not sure about all the drawbacks of breaking with existing Webmention.io-inspired tools, though.

[jalcine]

I think we might be a bit okay regarding breakage in a way! It's technically undefined behavior so implementations would have to update to match it. I also do lean a bit more towards Microsub's output especially since there's a concept of 'hidden' properties that we could potentially port the wm- prefixes over too.

[manton]

By the way, I'll probably continue to support JSON Feed as an option because the URL can be pasted into a feed reader to subscribe to new replies for that post. WordPress already has a built-in RSS feed for comments, but for static sites without their own comment storage, a feed could be useful.

[dshanske]

The Microsub JF2 is in my opinion the best approach..if we iterate on that in parallel. It has some more opinionated structure than mf2 json by design.

[jalcine]

The reasons above (needing to maintain compatibility and allowing for an option in the kind of format that they'd like to use) does nudge me towards using some sort of content negotiation here. However, for the simplicity of this, it seems like defining a similar subset of properties to the Posts output of Microsub would be ideal.

I think to keep the case that Manton describes, we could hint at making it need to say something like application/jf2+json (I forget the proper MIME type to use for JF2) and other formats that are wanted could respond accordingly (if they're not supported by the service).

[jalcine]

@manton Would you have your feed output be responsive to the Accept header? That would make it simple to allow other people to support doing the same and we can have the addition of it default to use the Microsub JF2 format for now.

[manton]

@jalcine I'd be fine with supporting Accept, although I'm not sure it's necessary in this case. I'd still want to support something like a format parameter so that you could paste the URL into a feed reader, which wouldn't be possible just with Accept.

[jalcine]

In #2, I mentioned a change that I'm tinkering with for https://indieweb.org/Lighthouse that wouldn't put too hard of a constraint on specifying the format (like it could be done via a Accept header or using a parameter).