w3c / w3c/activitystreams

Declaring `summary` to have markup other than `text/html`?

Open
#620 5 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Needs primer page needs-fep
Dominant language
HTML
Stars
313
Forks
70
PR merge metrics
No merged PRs in 30d

Description

Description of issue

name is defined as "A simple, human-readable, plain-text name for the object. HTML markup MUST NOT be included."

summary is defined as "A natural language summarization of the object encoded as HTML."

content includes in its definition that "By default, the value of content is HTML. The mediaType property can be used in the object to indicate a different content type."

So to synthesize these three definitions:

  • name is always text/plain
  • content is whatever the value of mediaType is, where mediaType defaults to text/html
  • summary is always text/html?

But there are cases where a producer might want to signal a different content type for summary; for example, text/plain or text/markdown. Recently, https://github.com/mastodon/mastodon/pull/32538 came up as an example of wanting to produce a summary that is NOT text/html. So the question is, might it make sense to provide a mechanism for declaring that summary is something other than text/html?

Potential solutions
  • Extending the definition of mediaType to cover both content and summary could work, but would prevent using different formats for each of the two separately.
  • Defining a separate property like mediaTypeOfSummary seems clunky, but might end up making sense or being necessary.
  • More explicit construction of a "text node" where every @value can have its own mediaType, although this would be pretty complicated and not backwards-compatible. (It would also break JSON-LD language containers, so nameMap/summaryMap/contentMap would not work.)
Action items
  • Needs Primer: guidance on the natural language properties, including a section on the content-type considerations (and potential sanitizing/stripping resulting from that)
  • Next Version: Possibly allowing summary to be something other than text/html, with either mediaType extending to cover it, or defining mediaTypeOfSummary as an analogous property.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing the definitions of name, summary, content, and mediaType in the Activity Streams specification, along with the listed potential solutions. Done means reaching a decision on whether summary may use a type other than text/html, documenting the chosen mechanism, and providing the requested Primer guidance on content types and sanitizing or stripping.

Written by the indexing model from the issue text.

Assessment

Tech stack
html
Domain
documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.