Archived: Documents in ActivityPub

Dave Winer asked me to take a look at the document What is a document? I decided to put my hat on as co-editor of ActivityStreams 2.0 (AS2) and co-author of ActivityPub (AP) to see how well our definitions met the features of a document.

Most of the “things” in AS2 are types of Object. We have three applicable Object types in ActivityStreams:

• Note – Represents a short written work typically less than a single paragraph in length. This is the type usually used for statuses, Tweets, or other microblogging items. The <1 paragraph requirement is rarely, if ever, enforced.
• Article – Represents any kind of multi-paragraph written work. This is probably the closest fit for what Dave’s looking for, but less frequently implemented than Note. I think it’s used for some apps that create longer-form text, like a blog post or a newspaper article.
• Document – Represents a document of any kind. The closest name match, but probably not the best in-use match. I’ve often seen this for non-HTML document attachments, like Word docs or PDFs.

Syntactically, any of these can be used with the primary elements of an Object, so I think they would all work OK.But I think the best match is Note, just because it’s widely implemented and the “single-paragraph” requirement is rarely enforced. A more strict interpretation would lean towards Article.

Here are the features that Dave suggested a document should have:

• Unlimited length – In AP and AS2, the “content” element of an Object, where the text is stored, has no length limit. However, many apps limit the content at input, and some will put longer content behind a “More…” link. One nice feature is that AS2 objects can have a shorter “summary” element, often an abstract or a lede, if the content is very long.
• Optional titles – Objects in AS2 have a “name” property that more or less takes the place of a title. Many processors ignore the “name” property for Note items, though. All properties of an Object are optional.
• Simple styling: italic, bold – The “content” element of an Object contains HTML5, included <i> and <b>. So we’re all good there! However, some clients will strip all markup from the content, or use style sheets to flatten it.
• Links – Lots of them! The “content” element of an Object contains HTML5, included <a>. There are also links in other properties of the Object. So this should be OK.
• Markdown support. So, there’s explicit support for a “mediaType” attribute of the “content” element, and we use Markdown as the main example in the document. But… I don’t think this is well implemented anywhere. In particular, I don’t think Mastodon has it.
• Audio enclosures for podcasting. Every Object can have an “attachment” array, with different kinds of objects, including Audio, attached. I haven’t checked how well Mastodon handles this, but it’s a pretty core part of the protocol.
• Documents can be updated. So important! AS2 support Create, Read, Update and Delete. ActivityPub is mostly about describing what happens when a server receives these activity types from other servers or from the client. That said, Mastodon has mixed support for them.

I’m really glad to see Dave working on this important topic. I’m going to share this blog post with him and get his feedback.

Published November 27, 2022