Use of 'summary' for object descriptions

The summary property can be used for providing summaries of objects, both activities and other things, as HTML text. I’m wondering how much to use/reuse/abuse this property. For example, if users of my software write one-line plain-text descriptions for some objects, I can publish those using summary, putting the text inside a <p> tag or something. But is that a good idea?

Pros:

  • Use an existing ActivityPub property

Cons:

  • It’s HTML, so all the guarantees and assumptions about the content are lost (e.g. if I want to embed it in a web page, I can’t assume it’s a one-line text etc., it’s basically an arbitrary chunk of HTML from another server
  • “summary” and “description” aren’t the same thing, so the name can be a bit misleading. You can describe a banana but you probably wouldn’t “summarize” a banana.

I’m leaning towards not using summary for anything but the general case where some arbitrary-HTML summary of something is provided. For everything else, including all cases where the description of something is known to be plain text, or needs to be a single-line text, or any requirement that is more specific than just-arbitrary-HTML-fallback-because-idk-how-to-display-this-object, use other properties.

How does this sound? I want to pick properties for stuff in ForgeFed, and replace all my uses of summary (e.g. for descriptions of repositories) with other properties (whether standard AP or external/extension). If that doesn’t sound right to someone, please explain :slight_smile:

name and summary are for natural language processing. there is no length limit. i don’t really see any issues. a one-line plain-text description can be used directly, no need for a <p> tag even. the only requirement is that name MUST NOT use html (since it is plain text, simple and human-readable), but summary can be any arbitrary string.

consider examples provided from the specs:


{"@context": "https://www.w3.org/ns/activitystreams",
 "type": "Person",
 "id": "https://social.example/alyssa/",
 "name": "Alyssa P. Hacker",
 "preferredUsername": "alyssa",
 "summary": "Lisp enthusiast hailing from MIT",

here, name and summary are basically the same as display-name and bio-text.


{
  "@context": "https://www.w3.org/ns/activitystreams",
  "type": "Note",
  "nameMap": {
    "en": "A simple note",
    "es": "Una nota sencilla",
    "zh-Hans": "一段简单的笔记"
  }
}
{
  "@context": "https://www.w3.org/ns/activitystreams",
  "name": "Cane Sugar Processing",
  "type": "Note",
  "summaryMap": {
    "en": "A simple <em>note</em>",
    "es": "Una <em>nota</em> sencilla",
    "zh-Hans": "一段<em>简单的</em>笔记"
  }
}

these two examples should demonstrate how name and summary are to be used.


i see no reason not to use summary for a description of what an object or activity represents. for the case of ForgeFed and repositories, it’s perfectly fine to have, for example:

[...]
"name": "forgefed/forgefed",
"summary": "An extension to ActivityPub for web-based Git services federation.",
[...]

similar to what Github has at the top of the repo. it is of course also possible to have your software enforce character limits on text entry or display, such as by truncating overflow text with ellipses.