From 3cf4383e5d86c3f666175c2fd6c319210e8f9003 Mon Sep 17 00:00:00 2001 From: tobi Date: Mon, 17 Nov 2025 13:37:51 +0100 Subject: [chore] Go back to using `name` for attachment alt text for now, add note in docs (#4559) # Description > If this is a code change, please include a summary of what you've coded, and link to the issue(s) it closes/implements. > > If this is a documentation change, please briefly describe what you've changed and why. This pull request switches us back to using the `name` property instead of the `summary` property for media descriptions for now, as using `summary` was causing accessibility issues with folks on *key, *oma, and Iceshrimp instances not being able to see GtS alt text, as those softwares (as of their latest releases I think) only look for `name`. Also updates the docs to add a note there on our intention to switch to using the HTML `summary` property instead of / in addition to `name` from v0.21.0 onwards. closes https://codeberg.org/superseriousbusiness/gotosocial/issues/4524 ## Checklist Please put an x inside each checkbox to indicate that you've read and followed it: `[ ]` -> `[x]` If this is a documentation change, only the first checkbox must be filled (you can delete the others if you want). - [x] I/we have read the [GoToSocial contribution guidelines](https://codeberg.org/superseriousbusiness/gotosocial/src/branch/main/CONTRIBUTING.md). - [x] I/we have discussed the proposed changes already, either in an issue on the repository, or in the Matrix chat. - [x] I/we have not leveraged AI to create the proposed changes. - [x] I/we have performed a self-review of added code. - [x] I/we have written code that is legible and maintainable by others. - [x] I/we have commented the added code, particularly in hard-to-understand areas. - [x] I/we have made any necessary changes to documentation. - [ ] I/we have added tests that cover new code. - [x] I/we have run tests and they pass locally with the changes. - [x] I/we have run `go fmt ./...` and `golangci-lint run`. Reviewed-on: https://codeberg.org/superseriousbusiness/gotosocial/pulls/4559 Reviewed-by: Daenney Co-authored-by: tobi Co-committed-by: tobi --- docs/federation/posts.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) (limited to 'docs/federation/posts.md') diff --git a/docs/federation/posts.md b/docs/federation/posts.md index 45a4fb7cd..7c92c297d 100644 --- a/docs/federation/posts.md +++ b/docs/federation/posts.md @@ -9,7 +9,14 @@ GoToSocial sends media attachments in the `attachment` property of posts using t - `Audio` - any audio type (mp3, flac, wma, etc). - `Document` - fallback for any other / unknown type. -Attachments sent from GoToSocial include the MIME `mediaType`, the `url` of the full-sized version of the media file, and the `summary` property, which can be interpreted by remote instance's as a short description / alt text for the attachment. +Attachments sent from GoToSocial include the MIME `mediaType`, the `url` of the full-sized version of the media file, and the `name` property, which can be interpreted by remote instance's as a short description / alt text for the attachment. + +!!! warning + According to ActivityStreams, `name` is "A simple, human-readable, plain-text name for the object" ([Link](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-name)). On the other hand, `summary` should be "A natural language summarization of the object encoded as HTML" ([Link](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-summary)). + + In light of `summary`'s better suitability as description / alt text, in future GoToSocial will switch to either using *only* the `summary` property instead of the `name` property, or will use *both* the `name` and `summary` properties (exact implementation tbd). This change will likely be introduced in version 0.21.0 of the software. + + This means the `summary` property transmitted by GoToSocial in v0.21.0 onwards will likely contain things like HTML `
` elements instead of newlines, escaped HTML characters, etc. Receiving instances should account for this when interpreting `summary` as alt text. Types `Image` and `Video` will also include the `http://joinmastodon.org/ns#blurhash` property so that remotes can generate a colorful hash of the image. If an audio file included an embedded cover art image, then the `Audio` type will also include a blurhash. See the [Mastodon blurhash docs](https://docs.joinmastodon.org/spec/activitypub/#blurhash). @@ -40,7 +47,7 @@ Here's an example of a `Note` with one attachment: 0.5 ], "mediaType": "image/jpeg", - "summary": "Black and white image of some 50's style text saying: Welcome On Board", + "name": "Black and white image of some 50's style text saying: Welcome On Board", "type": "Image", "url": "http://localhost:8080/fileserver/01F8MH17FWEB39HZJ76B6VXSKF/attachment/original/01F8MH6NEM8D7527KZAECTCR76.jpg" } -- cgit v1.2.3