A standard thing in ActivityPub is that there's content containing rendered rich text such as HTML, and source contains the source material and can be used for editing the content. The AS2 vocabulary spec describes the content property like this:

The content or textual representation of the Object encoded as a JSON string

What if an object has some rich text field but that field is not the "content" or "textual representation" of the object? And what if there are multiple rich text fields? For these cases, I want to ask:

• Which property to use for the HTML?
• Which property to use for the Markdown source?
• Which properties to use for media types?

I want to give specific examples and be very precise about what I'm asking.

Question 1: Placing the source field

Imagine there's a property description and we want it to contain HTML, and we also want to provide Markdown source. One hypothetical very scary way to do this is to define a dedicated properties for the source and media type:

{ "@context": "...",
  "id": "https://...",
  "content": "This is the content of this object",
  "description": "<p>Here's some <b>bold</b> text</p>",
  "descriptionMediaType": "text/html",
  "descriptionSource": {
    "content": "Here's some **bold** text",
    "mediaType": "text/markdown"
  }
}

Another way, perhaps a nicer way is to do something like this:

{ "@context": "...",
  "id": "https://...",
  "content": "This is the content of this object",
  "description": {
    "content": "<p>Here's some <b>bold</b> text</p>",
    "mediaType": "text/html",
    "source": {
      "content": "Here's some **bold** text",
      "mediaType": "text/markdown"
    }
  }
}

Does the 2nd way look reasonable? Shall we do it like this? The downside is that description doesn't have an obvious type as its range. AP doesn't define a range type for the source property. Are we ok with that? Or do we want do define/propose a type for this? We could call it Content or something. Idk.

Question 2: How much to use content

For a Note, the content is the true actual essence of the note. When you talk about writing a note, the stuff you write is what's in the content. But imagine something like Banana, and we want to specify a description of this banana, e.g. "A sweet delicious yellow ripe organic banana". Do we put this text under the content property? I'm asking because this text is clearly not the content of the banana. The content is a physical object you're about to eat, in the physical world.

Another example, imagine a Merge Request submitted against one of your Git repos. The Merge Request probably has a title, and a longer description, and then there's the actual commits that the submitter made. Do we put the Merge Request's description in content? I'm asking because the actual content, essence, of the merge request is the commits, not the description.

So, I'm wondering: Should we use content when there's a single description field for an object, even if it's not the actual content and just a textual description/representation, or should we use other properties, and reserve content for use with the actual essence of the object (when the essence is textual; since the range of content is xsd:string so it can't be e.g. a list of commits)?

Feneas forum thread

DECISION: Put source alongside content and mediaType, e.g. all 3 of them can be under a description.

QUESTION: Should we always use content directly for textual aspect of objects (e.g. a commit message or ticket description), or put content under description (which is what the spec currently says)?

I opened a separate issue for this, #24. See there.