Media Upload Endpoint and Remote Media Library

[Jiwoon-Kim]

This post expands on some ideas mentioned in [#2314 – Add Attachments processor class for handling ActivityPub media](#2314), particularly around how remote vs. local media handling should work in WordPress.

---

1. Background

Recent improvements such as smart media markup and inline image handling have raised an important architectural question:
How should ActivityPub attachments (media objects) be handled differently from direct media file links?

Platforms like Mastodon cache all attachments locally, but WordPress operates with a Media Library, which introduces a fundamentally different model.
Therefore, the optimal approach may depend on the object type (e.g., Article vs. Note) and the presence of a media library endpoint.

---

2. Key distinctions

Media file direct links

• Represent one-time use links to files (usually hotlinked).
• Cannot be proven to be the same object across federated systems.
• Should remain as remote URLs rather than being imported into the Media Library.

Media objects

• Represent structured, reusable entities that imply the existence of a Media Library and an Upload Endpoint.
• May require an endpoint such as ?remote_attachment_id=123 for access and federation.
• Are ideal for inclusion of JSON-LD representations via the attachment page.

---

3. Proposed workflow

1. Load attachment JSON-LD metadata first.
   Then apply lazy loading for inline images or gallery blocks based on viewport size.

2. Implement remote media objects as hotlinks by default.
   The content of a remote image object remains a hotlink unless explicit reuse permission (license) is declared.

3. Optional local caching with license extension.
   If a [FEP-c118 Content Licensing](https://codeberg.org/fediverse/fep/src/branch/main/fep/c118/fep-c118.md) policy is detected, the system may:

   • Cache the file locally.
   • Replace the file URL with a local one.
   • Preserve the original URI for attribution.

4. Remote attachment persistence.
   Remote media attachment pages can remain even after the original post is deleted, since they may be reused or referenced via the media library.

---

4. Inline images and multiple versions

According to [FEP-b2b8: Long-form Text](https://codeberg.org/fediverse/fep/src/branch/main/fep/b2b8/fep-b2b8.md#content),

Any embedded media in the content property should also be listed in the attachment property.

However, WordPress’s Gutenberg system often uses gallery blocks with multiple image versions.
This makes simple inline-image models insufficient.
A better approach could follow the principles of [FEP-1311](https://codeberg.org/fediverse/fep/src/branch/main/fep/1311/fep-1311.md) (multiple media versions) and [FEP-e232](https://codeberg.org/fediverse/fep/src/branch/main/fep/e232/fep-e232.md) (object links).

For performance, Articles might reference a container URI (improved attachment_id permalink) that serves all image versions.

---

5. Relation to core proposals

• Improving the Permalink Structure for ?attachment_id=123
• [Media Library Improvements](https://make.wordpress.org/core/2023/07/07/media-library/)
• [AI: Building Blocks – Media Library](https://make.wordpress.org/ai/2025/07/17/ai-building-blocks/)

These efforts align naturally with the goal of introducing a Remote Media Library and Media Upload Endpoint for federated environments.

---

6. Conclusion

In summary:

• Media file direct links and media objects should be clearly separated.
• The attachment page is the best place for JSON-LD representation of media objects.
• Hotlink-first behavior improves performance, while license-based local caching supports proper attribution and reuse.
• Future extensions could allow federated commenting (inReplyTo) on remote media attachment pages once the underlying endpoint exists.

I’ll continue exploring this idea under the title “Media Upload Endpoint and Remote Media Library.”

[Jiwoon-Kim]

Media Upload Endpoint and Remote Media Library

Smart media markup: Generates blocks (or shortcodes) with gallery support for multiple images
4. The current version does not side-load inline images. I think we should support inline images and ignore attachments that reference the same one.

The appropriate approach may vary depending on the object type,
so direct image file links and image objects may require different attachment fetching behavior.

My current idea is to first load the JSON-LD metadata of all attachment objects, then render the appropriate image size version according to the viewport value, applying lazy loading to inline images or gallery blocks within the content field.
This way, better performance and flexibility can be provided without local uploads.

To implement inline images in the content field of an article, an extension of the HTML markup language is required.
In fact, even now, in wp-to-wp cases, when an ActivityPub object is embedded, the Gutenberg gallery block works. However, you cannot comment on the image carousel.
If a remote WordPress instance queries the remote media library through the media upload endpoint and stores the remote image object in ?remote_attachment_id, then when commenting, it becomes possible to federate replies to the remote attachment page (image object). After implementing this, if an official FEP extension is later added, it will enable other CMSs to post federated comments on attachment pages as well.

Remote URL support: Downloads and imports media from ActivityPub network

Metadata preservation: Stores source URLs and alt text for images

We should not add external Attachments to the Media-Library. This is very spammy and floods the internal media handling with external media.

Yes, I know that Mastodon caches all attachment images locally, but WordPress operates on a very different architecture.
There is a difference between platforms that have a media library and those that don’t.

If there is no media library, implementing the media object endpoint will be difficult, so the existence of a media object can be assumed to mean that a media library and media upload endpoint exist.
If a media object exists, it can be reused. However, in the case of a direct media file link, it cannot be proven in ActivityPub that it is the same entity, so it is one-time. Therefore, in the case of WordPress, there is no reason to store such media locally.

My opinion is that for this reason, media file direct links and media objects should be clearly distinguished. The attachment page is the ideal location because it includes the JSON-LD representation of the media object.

For platforms that have a media library,
a page such as ?remote_attachment_id may be required.
Such pages are created only for media objects.

In fact, most microblogging platforms in the Fediverse do not have media libraries.
Therefore, platforms like Mastodon, Pixelfed, and Threads attach direct media file links in the attachments field.
For directly attached media files, ?remote_attachment_id pages are not generated.

In both cases, I think the default behavior should maintain hotlinking (remote connections).

I think the content of a remote image object should basically maintain a hotlink.
Depending on the implementation, it is also possible to record it only in the database and use it without uploading the file itself to local storage.

When license extensions are applied, files are optionally cached locally, and the file URL is replaced with a local URL only when explicit reuse permission is granted, but the original URI is preserved.
https://codeberg.org/fediverse/fep/src/branch/main/fep/c118/fep-c118.md
FEP-c118: Content licensing support

2. When I delete a post, the Media-Attachment will not be deleted with the post.

The fact that remote media attachments remain even after the remote article is deleted is normal, because it means the media can continue to be reused through the media library.

• Local file support: Processes files from Mastodon archive imports

https://fedi.tips/how-to-download-your-mastodon-post-archive/
I looked up what Mastodon archive imports are, but they don’t seem to be related to federation.
I think local file support should be solved by improving media library behavior.

---

Additional reference materials

#2146 (comment)
"Shared media library between instances"

#2145
Improvements: The ActivityPub Object Representation for media attachment posts is missing. #2145

https://make.wordpress.org/core/2023/07/07/media-library/

On the management side, it’s time to look at categorization and tagging, better handling of attached media, design improvements to the library views and filtering. Several important functionalities are already present but not presented in the best way. For example, media attachment functionality (items anchored to a specific post) is often hard to discover, the interface is not the most intuitive, and the connection doesn’t necessarily carry through other editing flows in a clear way. For larger teams, media ingestion can often be an entirely separate process from writing posts. The ability to bulk attach media files and connect them to the relevant content pieces is thus an important part of the collaborative process.

When managing the media library, it should be easy to check and keep track of attribution. As we look into expanding the presence and touch points of [Openverse](https://openverse.org/), it’d be interesting to see how contributions to the commons could work directly from a user’s WordPress install. Another area to look at is improving handling and presentation of other media types (audio, video, files) and their connection with blocks and the block APIs. We should resurface work on a native Playlist block, ideally powered by the [Interactivity API](https://make.wordpress.org/core/2023/03/30/proposal-the-interactivity-api-a-better-developer-experience-in-building-interactive-blocks/).

Finally, we should take a look at the publishing flows for media and format driven posts (where only one block type is present) to allow more expressive freedom.

https://make.wordpress.org/ai/2025/07/17/ai-building-blocks/

Media Library
Using AI to create and edit media is becoming increasingly popular. Additionally, there are many smaller implementations that AI could help with: auto alt text and captioning, intelligent grouping, multimodal search capabilities, and more.

https://core.trac.wordpress.org/ticket/63953
Improving the Permalink Structure for ?attachment_id=123

---

#2270

Inline images and attachments

All inline images in an Article should also appear in attachments.
FEP-b2b8: Long-form Text
https://codeberg.org/fediverse/fep/src/branch/main/fep/b2b8/fep-b2b8.md#content

Any embedded media like images, video or audio in the content property should also be listed in the attachment property so that consumers can pre-fetch the media.

FEP-1311: Media Attachments introduces the concept of multiple media versions and licensing.
https://codeberg.org/fediverse/fep/src/branch/main/fep/1311/fep-1311.md#multiple-media-versions

FEP-e232: Object Links
https://codeberg.org/fediverse/fep/src/branch/main/fep/e232/fep-e232.md
This could be useful for inline images as object links.

Issue with WordPress:

• Single inline images are less common than galleries.
• The gallery block often includes multiple media versions in the content itself.
• A simple inline-image model is insufficient.
• A more flexible approach may resemble FEP-c16b (Formatting MFM functions).

---

Multiple media versions

For heavy photologs (up to 50 images per post), embedding all versions in the Article object is inefficient.

• Articles should reference an attachment container URI (e.g., improved attachment_id permalinks).
• The container provides access to all media versions.
• The attachment property should only include the representative URI + main URL.
• [UploadMedia endpoint](https://www.w3.org/TR/activitypub/#uploading-media) can be used to handle version arrays more efficiently.

Related core proposal:
https://core.trac.wordpress.org/ticket/63953
Improving the Permalink Structure for ?attachment_id=123

[Jiwoon-Kim]

https://docs.akkoma.dev/stable/development/ap_extensions/#uploadmedia

Deprecated and Removed Extensions

The following extensions were used in the past but have been dropped. Documentation is retained here as a reference and since old objects might still contains related fields.

Actor endpoints

The following endpoints used to be present:

• uploadMedia (https://www.w3.org/ns/activitystreams#uploadMedia)

uploadMedia

Inspired by https://www.w3.org/wiki/SocialCG/ActivityPub/MediaUpload, it is part of the ActivityStreams namespace because it used to be part of the ActivityPub specification and got removed from it.

Content-Type: multipart/form-data

Parameters: - (required) file: The file being uploaded - (optional) description: A plain-text description of the media, for accessibility purposes.

Response: HTTP 201 Created with the object into the body, no Location header provided as it doesn't have an id

The object given in the response should then be inserted into an Object's attachment field.

---

As you know, Lemmy includes ActivityStreams Dislike activities, which are not part of the official ActivityPub specification. I believe that CMS platforms like WordPress or Ghost absolutely need an uploadMedia endpoint.

Exactly — the uploadMedia endpoint is one of those things that got deprecated from the formal ActivityPub spec, but in practice, many CMS implementations like WordPress or Ghost still need a way to receive and process media uploads.

Here’s why it matters:

---

🔹 Context

• ActivityPub vs ActivityStreams: ActivityPub defines actors, objects, and activities, but it doesn’t mandate media upload endpoints. Media handling is often left to implementations.
• uploadMedia: Historically, it allowed an actor to send a file (image, audio, video, document) via multipart/form-data and receive an object representing the media. That object could then be referenced in an attachment field of a Note, Article, or other object.
• Lemmy and similar: Lemmy has dislike activities that aren’t part of official ActivityPub, showing that practical implementations often diverge.

---

🔹 Why CMS need it

1. Direct media attachment: When creating posts with images or videos, users expect to attach media directly instead of just hotlinking.
2. Remote federation: Without an endpoint to handle uploads, federated instances can only reference remote media, which breaks workflow for inline attachments.
3. JSON-LD object creation: The uploaded media object can carry metadata like name, mediaType, url, duration, etc., enabling richer display and semantic interoperability.

---

🔹 Practical approach

For WordPress or Ghost:

1. Implement an uploadMedia endpoint on the actor (user) resource.
2. Accept file (required) and description (optional) as multipart/form-data.
3. Create a media object, store it locally, and return it in the response.
4. Allow posts (Note, Article) to reference this media object in their attachment field.
5. Optional: support remote caching, licensing metadata, and different media versions for performance.

---

In short: even if deprecated in spec, uploadMedia is essential for real-world CMS that want robust ActivityPub federation with media support.

If you want, I can draft a WordPress-style uploadMedia implementation plan that fits current FEP guidelines and the Media Library model. Do you want me to do that?

[Jiwoon-Kim]

@Menrath Personally, I think it’s better to handle post-type objects like Article and Note separately from media-type objects like Image, Video, and Audio.
Since the uploadMedia endpoint is already defined and object retrieval is supported,
I believe we could implement a local user uploadMedia endpoint on the frontend through extensions of the Media Library and Attachment Page features.

• https://www.w3.org/TR/activitypub/#uploading-media
• https://www.w3.org/wiki/SocialCG/ActivityPub/MediaUpload#uploadMedia
• https://www.w3.org/TR/activitypub/#retrieving-objects

However, I’m not entirely sure whether it’s truly necessary to parse the attachment property from a remote actor’s Note or Article and store it in the local media library.
For example, even if a WordPress hosting plan provides an unlimited database, it might only offer 1 GB of storage.
If the system automatically caches all external media from remote actors, the local site’s storage could quickly fill up with spam, effectively preventing any further media uploads.

That’s why I suggested that direct file links should be treated as hotlinks,
and that we should only record them in the database (as something like remote_attachment_page)
when the actor has an uploadMedia endpoint and the object is a genuine media object.

In any case, implementing remote media local caching now could still be useful later,
since it would provide reusable infrastructure when implementing selective local caching in the future.
So while I don’t oppose the current PR, I can’t say I fully agree with its direction.

---

I wanted to suggest that WordPress could independently implement a sharedMedia endpoint to enable the reuse of remote media objects.

[pfefferle]

The media upload is mainly for Client2Server communication, it is not meant to be used by Server2Server interactions.

[Jiwoon-Kim]

Ah, what I mean by media object federation through a media library endpoint is something like this:

👉 https://wordpress.org/photos/author/kimjiwoon/
👉 https://openverse.org/ko/image/collection?source=wordpress&creator=Jiwoon+Kim

That’s the kind of federation concept I have in mind.

[Jiwoon-Kim]

I’ve been thinking a bit more about the concept, and I’d describe it as essentially a pull model for media objects.

In WordPress, when a post is published, it pushes an Activity to synchronize the object.
For media, however, the idea is to create the object without pushing a Create activity when it’s uploaded to the media library — meaning the object simply exists and can later be pulled or fetched when needed.

References:

• [Stack Overflow: ActivityPub / Mastodon — how to get an actor](https://stackoverflow.com/questions/75025657/activitypub-mastodon-how-to-get-an-actor)
• [Wikipedia: Trust on first use](https://en.wikipedia.org/wiki/Trust_on_first_use)
• [W3C ActivityPub — Retrieving Objects](https://www.w3.org/TR/activitypub/#retrieving-objects)

---

It’s not about caching the media directly from the attachments property of an Article, but rather about storing the metadata — such as the URI, alt text, and multiple size variants — of the media objects linked in the attachment property within the database.
Then, only the images that are actually intended for reuse can be selectively cached locally from their direct file URLs.

I believe it should be possible not only to synchronize but also to simply query media objects from the mediaLib endpoint, without having to store all of them in the local database.
Think of it like the difference between OneDrive file synchronization and accessing files through a web app — both connect to the same source, but only one actually downloads and stores the data locally.

[pfefferle]

I still don't get the real advantage of that. I think the sideloading of the image is a simple and straightforward solution if you want a local cache and if you want to use hotlinking you literally have nothing todo.

You have to keep in mind that WordPress is a CMS that normally runs in shared hosting envs. So the main goal should be to keep it as simple stupid as possible.

[Jiwoon-Kim]

In my opinion,
when an image included in the attachments property of a Note received from Mastodon is locally cached in WordPress, it automatically generates the Thumbnail, Medium, Large, and Full Size versions.
Is this the expected behavior?

I think such excessive processing is undesirable and should be avoided whenever possible.

On the other hand, for image objects generated by WordPress itself,
I believe they should by default include an array of Thumbnail, Medium, Large, and Full Size versions.
(Of course, the exact dimensions may vary by site, but including multiple sizes helps WordPress optimize media usage.)

However, should all of these versions really be uploaded individually to local storage?

[Jiwoon-Kim]

2.3. Local Caching Strategy for Remote Image Assets
#2371

[Jiwoon-Kim]

@pfefferle

📁 Attachment (Media) Hierarchy in WordPress

• Template Hierarchy: Attachment (Media)
• Attachment Template Files
• Template Hierarchy: Attachment (Classic Themes)
• Post Types: Attachment

💬 “The use case for using attachment pages is to make the media library publicly accessible. I know lots of photographers use WordPress for doing just that.”
— Make WordPress Core: Changes to Attachment Pages

---

🖼️ Image Versions and Media Object Federation

When you upload an image in WordPress, multiple size versions are automatically generated.
Following the proposal in FEP-1311: Media Attachments, a media object can include multiple versions of the same image.

Relevant references:

• WordPress Media Settings: Image Sizes
• FEP-1311: Media Attachments → Multiple Media Versions
• FEP-c118: Content Licensing Support

Related WordPress documentation:

• Media Library Overview
• Controlling WordPress Image Sizes
• Media Library Screen
• Editing Media
• Image Block Settings
• Inserting Images in Classic Editor
• MDN: Image Formats and Types

---

🧩 Inline Images and Attachment Implementation

When implementing inline images from the content property of an ActivityPub Object via its attachments, the following WordPress documentation is useful:

• Gallery Shortcode

• Using Image and File Attachments in Themes

  Themes may use various template tags to display post attachments or utilize the attachment.php file to customize the display of attachments. A shortcode tag is also available to display a gallery of images attached to a post.

---

📚 Followable Collections

I’m also exploring the concept of followable collections, similar to Pinterest boards:

• Pinterest Help: Find and Follow Boards

Related FEPs:

• FEP-a974: All Actor Types Should Be Followable

• FEP-2931: Collections Cannot Be Cleanly Followed via C2S Outbox Delivery

  If you wish to make a Collection followable, the naive approach is to make it into an ActivityPub actor by giving it an inbox that can at least respond to Follow activities with an Accept.

---

🧠 Additional FEP References

• FEP-5bf0: Collection Sorting and Filtering
• FEP-fe34: Origin-Based Security Model
• FEP-9fde: Mechanism for Servers to Expose Supported Operations
• FEP-96ff: Explicit Signaling of ActivityPub Semantics
• FEP-3b86: Activity Intents

---

😊 Custom Emoji Integration

WordPress already supports smilies, which could be adapted to display remote instance custom emojis:

• WordPress Docs: What Are Smilies?

---

[Jiwoon-Kim]

@pfefferle I believe that for Media objects, there should be a dedicated object collection endpoint that allows querying the objects directly — without pushing Create activities to the outbox.

A WordPress-specific Media Library extension would be needed for this purpose.

References:

• Mastodon’s featured collection:
  https://docs.joinmastodon.org/spec/activitypub/#featured
• Misskey’s vCard-like extension:
  https://www.w3.org/wiki/Activity_Streams_extensions

[Jiwoon-Kim]

@pfefferle I’ve looked further into C2S and S2S, and while I’m still not entirely sure how S2S should be implemented, I’m completely certain that for C2S, the uploadMedia endpoint should correspond directly to the media library upload in WordPress.

[Jiwoon-Kim]

And it would be good for media objects included in the attachments property to have a source attribute.
Also, just as the inReplyTo property is collected into the replies collection, I think the attachment property should be collected into an attachedTo collection.

[pfefferle]

Sure, but the plugin does not support C2S (yet).

[Jiwoon-Kim]

However, that’s one thing for newly uploaded media —
but applying the ActivityPub object extension to files' attachment pages already uploaded in the media library,
and exposing them through the uploadMedia endpoint,
is a completely different matter.

[Jiwoon-Kim]

I discovered something quite shocking: you should never use an Image object directly inside the attachment property of a WordPress post.

In WordPress, the media library is responsible for generating and storing the actual image objects, while the attachment property of a post should only reference them via links — not embed full Image objects.

There have been discussions around using content-addressable identifiers such as digestMultibase, but personally, I believe it’s sufficient to include the mediaType attribute in the Link and ensure that the id of the Link matches that of the referenced object.

---

https://www.w3.org/TR/activitypub/#source-property
https://www.w3.org/TR/activitypub/#obj-id
https://www.w3.org/TR/activitystreams-vocabulary/#dfn-id
https://www.w3.org/TR/activitystreams-vocabulary/#dfn-image
https://www.w3.org/TR/activitystreams-vocabulary/#dfn-url
https://www.w3.org/TR/activitystreams-vocabulary/#dfn-attachment
https://www.w3.org/TR/activitystreams-vocabulary/#dfn-mediatype
https://www.w3.org/TR/activitystreams-vocabulary/#dfn-link
https://www.w3.org/TR/activitystreams-vocabulary/#dfn-href
https://www.w3.org/TR/activitystreams-vocabulary/#dfn-rel
https://www.w3.org/wiki/SocialCG/ActivityPub/MediaUpload#uploadMedia
https://codeberg.org/fediverse/fep/src/branch/main/fep/1311/fep-1311.md#multiple-media-versions
https://codeberg.org/fediverse/fep/src/branch/main/fep/1311/fep-1311.md#content-addressed-storage
https://socialhub.activitypub.rocks/t/brainstorming-on-fediverse-media-storage-improvements/4272
https://w3c.github.io/vc-data-integrity/#resource-integrity
https://codeberg.org/fediverse/fep/src/branch/main/fep/cd47/fep-cd47.md
https://github.com/mastodon/mastodon/blob/main/app/lib/attachment_batch.rb

---

Proposed Improvements

It would also be good if media objects included in the attachment property had a source attribute, as defined in the ActivityPub specification:

ActivityPub §3.4: The source Property

In addition, similar to how the inReplyTo property is aggregated into a replies collection, I believe the attachment property should likewise be aggregated into an attachedTo collection — allowing more consistent reverse lookups and discoverability of media-related relationships.

---

Relevant References

• Object id
  Provides the globally unique identifier for an Object or Link.

• Image object
  An image document of any kind.
  Example:

  {
    "@context": "https://www.w3.org/ns/activitystreams",
    "type": "Image",
    "name": "Cat Jumping on Wagon",
    "url": [
      {
        "type": "Link",
        "href": "http://example.org/image.jpeg",
        "mediaType": "image/jpeg"
      },
      {
        "type": "Link",
        "href": "http://example.org/image.png",
        "mediaType": "image/png"
      }
    ]
  }

• Attachment
  Identifies a resource attached or related to an object that may require special handling.
  Example:

  {
    "@context": "https://www.w3.org/ns/activitystreams",
    "type": "Note",
    "name": "Have you seen my cat?",
    "attachment": [
      {
        "type": "Image",
        "content": "This is what he looks like.",
        "url": "http://example.org/cat.jpeg"
      }
    ]
  }

• MediaType
  When used on a Link, identifies the MIME media type of the referenced resource.
  Example:

  {
    "@context": "https://www.w3.org/ns/activitystreams",
    "type": "Link",
    "href": "http://example.org/abc",
    "hreflang": "en",
    "mediaType": "text/html",
    "name": "Next"
  }

• Link
  A Link is an indirect, qualified reference to a resource identified by a URL.

---

Comparison Between Mastodon and WordPress Implementations

Using ActivityPub Explorer, I compared the attachment property in two different posts:

Mastodon Note

https://mastodon.social/@thaumiel999/115388078017230651

"attachment": [
  {
    "type": "Document",
    "mediaType": "image/jpeg",
    "url": "https://files.mastodon.social/media_attachments/files/115/388/077/548/299/024/original/3e5bb134e4ce6bf6.jpg",
    "name": null,
    "blurhash": "UkL;jSWBWEs:t7j[WBay~qoft7azR*WBofj[",
    "width": 709,
    "height": 918
  },
  {
    "type": "Document",
    "mediaType": "image/jpeg",
    "url": "https://files.mastodon.social/media_attachments/files/115/388/077/651/773/360/original/cbc3ae89fb7a12ff.jpg",
    "name": null,
    "blurhash": "UWK1wK_NDjt6?vozRjt7D*s.WAR*M|t6RPWB",
    "width": 736,
    "height": 544
  },
  {
    "type": "Document",
    "mediaType": "image/jpeg",
    "url": "https://files.mastodon.social/media_attachments/files/115/388/077/742/211/858/original/e12ecdd557b94725.jpg",
    "name": null,
    "blurhash": "UEJt;lWqbH-:-;tQ9GD*xbe.W=Rk~pIV?G?Z",
    "width": 760,
    "height": 801
  },
  {
    "type": "Document",
    "mediaType": "image/jpeg",
    "url": "https://files.mastodon.social/media_attachments/files/115/388/077/826/994/996/original/e61959d9e2e0f137.jpg",
    "name": null,
    "blurhash": "UCG8o-?bN{RjT{WCIVIo0LjEIURj0Lf5xaay",
    "width": 754,
    "height": 781
  }
]

WordPress.com Note

https://kimjiwoon96.wordpress.com/2025/10/11/251011-%eb%8f%99%ec%95%84%eb%8c%80-%ec%8a%b9%ed%95%99%ec%82%b0-%eb%91%98%eb%a0%88%ea%b8%b8/

"id": "https://kimjiwoon96.wordpress.com/?p=8099",
"type": "Note",
"attachment": [
  {
    "type": "Image",
    "url": "https://kimjiwoon96.wordpress.com/wp-content/uploads/2025/10/20251011_180821.webp?w=1024",
    "mediaType": "image/webp"
  },
  {
    "type": "Image",
    "url": "https://kimjiwoon96.wordpress.com/wp-content/uploads/2025/10/20251011_154338.webp?w=1024",
    "mediaType": "image/webp"
  },
  {
    "type": "Image",
    "url": "https://kimjiwoon96.wordpress.com/wp-content/uploads/2025/10/20251011_165805.webp?w=1024",
    "mediaType": "image/webp"
  },
  {
    "type": "Image",
    "url": "https://kimjiwoon96.wordpress.com/wp-content/uploads/2025/10/20251011_165847.webp?w=1024",
    "mediaType": "image/webp"
  }
]

In this comparison, Mastodon correctly uses Document objects with mediaType, url, and extended metadata (width, height, blurhash), while WordPress simply embeds Image objects directly — which violates ActivityStreams best practices.
Instead, WordPress should reference each media item via Link objects that point to the media file, not embed them inline as full Image objects.

---

UploadMedia Endpoint and File/Object Separation

The W3C SocialCG Media Upload specification defines the uploadMedia endpoint for Client-to-Server (C2S) interactions only — it is not standardized for Server-to-Server (S2S), and would require either a Fediverse Enhancement Proposal (FEP) or a nonstandard extension.

However, what’s crucial is the specification’s explicit separation between file and object:

The submitted form data should contain two parts/fields:

• file: the actual media file being uploaded.
• object: a shell of an ActivityStreams object, which will be finalized by the server.

And further:

The server, after processing the received file and placing it appropriately, transforms the object retrievable by the id. Specifically, servers MUST append an id property to the object and SHOULD include the uploaded and/or processed file paths in the object’s url property. The server MAY wrap the shell object in a Create activity if appropriate and expose this as the object pointed to by the Location header in the response.

---

The WordPress Irony

Ironically, this separation between file and object is exactly how WordPress already operates.
In WordPress:

• A file (the actual media binary) is stored in /wp-content/uploads/.
• An attachment page (a post of type attachment) holds metadata such as title, caption, alt text, and contextual relations.

Thus, WordPress’s internal model already mirrors ActivityPub’s conceptual separation between resource (file) and metadata object (ActivityStreams Document/Image).

Therefore, the attachment objects in ActivityPub JSON should correspond not to raw media files, but to these attachment post objects — containing descriptive metadata, context, and links to the underlying media resources.

[Jiwoon-Kim]

If I didn’t misunderstand, every Object must absolutely have an id, right?
https://www.w3.org/TR/activitypub/#obj-id

All Objects in [ActivityStreams] should have unique global identifiers.

https://www.w3.org/TR/activitystreams-vocabulary/#dfn-id

Even for Link objects, it seems like an id is required in addition to href, right?

And even for Link objects, they can have a media type of image and the example you mentioned can still apply, right?

---

Ah, since a Link is disjoint with an Object, it doesn’t necessarily need to have an id.
However, it should be fine to include a representative image and an id inside a preview property.

[pfefferle]

This is a "should" not a "have to". Please check the two examples I shared! These image objects are attachments no top level objects, they are part of a post and there is no need to look them up directly.

If we add an id, it is not as simple as adding the permalink. This link has to provide all the necessary JSON, so we would have to implement content negotiation for attachments and there is currently no benefit from this extra work!

[Jiwoon-Kim]

Yes… I understand for now. I had thought it would be a simple mapping since the Image object id exactly matches the attachment page ID, but it seems it’s not that straightforward.

I treat the attachment page and the block editor inline images as separate entities. That’s why I approached it this way.

The reason is that the Image object id is necessary in a WP-to-WP federation scenario, so that comments can be made on someone else’s media library. I hope you understand that my intention was to integrate this behavior with WordPress core functionality.

---

We implement a mediaLib endpoint that returns a list upon a GET request.
In a POST request, the attachment field explicitly specifies the id of the Image object.

Through this mechanism, we enable media library comment interactions within the WP-to-WP federation scenario.
That’s all there is to it.

[Jiwoon-Kim]

Image object caching and image file caching are fundamentally different concepts.
The URL of an Image object can contain an array of Link objects,
which means the object itself represents a semantic and relational entity — not merely a static file reference.
Therefore, caching the Image object concerns metadata and federated identity,
whereas caching the image file concerns binary data and delivery optimization.

---

In Mastodon, the absence of an id field in an Image object implies that the image is not an independent ActivityPub entity,
but merely an inline media element — effectively part of the Note’s content, not an addressable object.
In WordPress, however, media items (attachments) are first-class entities with their own permalinks, metadata, and comments.

Therefore, if the Image object lacks an id, WordPress would logically treat it as a hotlinked inline image
(i.e., part of the content block, using alt text for accessibility), rather than as a federated media resource.
Including an id — even if it maps to an internal attachment post — allows WordPress to maintain
a proper object reference model, enabling comments, reuse, and ActivityPub interoperability.

[pfefferle]

Exactly and what we are currently working on is a simple image file caching.