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)?
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:
```json
{ "@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:
```json
{ "@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](https://talk.feneas.org/t/editable-rich-text-fields/185)
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.
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.
A standard thing in ActivityPub is that there's
content
containing rendered rich text such as HTML, andsource
contains the source material and can be used for editing the content. The AS2 vocabulary spec describes thecontent
property like this: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:
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:Another way, perhaps a nicer way is to do something like this:
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 thesource
property. Are we ok with that? Or do we want do define/propose a type for this? We could call itContent
or something. Idk.Question 2: How much to use
content
For a
Note
, thecontent
is the true actual essence of the note. When you talk about writing a note, the stuff you write is what's in thecontent
. But imagine something likeBanana
, 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 thecontent
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 reservecontent
for use with the actual essence of the object (when the essence is textual; since the range ofcontent
isxsd:string
so it can't be e.g. a list of commits)?Feneas forum thread
DECISION: Put
source
alongsidecontent
andmediaType
, e.g. all 3 of them can be under adescription
.QUESTION: Should we always use
content
directly for textual aspect of objects (e.g. a commit message or ticket description), or putcontent
underdescription
(which is what the spec currently says)?I opened a separate issue for this, #24. See there.