documentation/event_import.md

132 lines
No EOL
8.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

---
gitea: none
include_toc: true
---
Status: draft. This document should be reviewed by the other main developers.
# Validation/Import of remote events
This document gives an overview how remote `Event` objects are treated by common Fediverse applications.
## Mastodon
**Last updated**: 2024-10-20
Mastodon does not have support or events, but an `Event` object is in the [list of converted object types](https://github.com/mastodon/mastodon/pull/12637/commits/0428c00e30abcb0580558f9bdca672abc8b68f81).
It neglets all event related fields but `title`, `summary` and `url` which it uses to create a Mastodon status (toot) representation of the event.
## Mobilizon
**Last uptaded**: 2024-01-20
**Information sources**:
- [Mobilizon ActivityStreams converter for Event](https://framagit.org/framasoft/mobilizon/-/blob/main/lib/federation/activity_stream/converter/event.ex?ref_type=heads)
- [Mobilizon Database schema for Event](https://framagit.org/framasoft/mobilizon/-/blob/main/lib/mobilizon/event.ex?ref_type=heads)
### Required
- [`attributedTo`](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-attributedTo) or [`actor`](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-actor): Mobilizon uses actor for the user profile and attributedTo for the group. But as `actor` being part of an object is not part of the ActivityPub spec, solely using `attributedTo` might preferred if they are similar.
- `id`: This is also used for the `url`.
- [`name`](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-name): The events title.
- [`startTime`](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-startTime)
- [`to`](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-to)
- [`type`]: must be `Event`
### Optional
- [`attachment`](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-attachment) How they are used
- [`anonymousparticipationenabled`](https://docs.joinmobilizon.org/contribute/activity_pub/#anonymousparticipationenabled)
- `category`: default list of categories can be found [in the source code](https://framagit.org/framasoft/mobilizon/-/blob/main/lib/mobilizon/events/categories.ex?ref_type=heads#L28), but it can be extended via environment variables. Note that the source code shows them in lowercase, but they have to be passed as uppercase, e.g. `MOVEMENTS_POLITICS`.
- [`commentsEnabled`](https://docs.joinpeertube.org/api/activitypub)
- `contacts`: a list of contacts: each item might be just the `id`/`url` or an `Actor` object.
- [`content`](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-content): `contentMap` is currently not supported by Mobilizon.
- [`endTime`](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-endTime)
- `externalParticipationUrl`: Only used if `joinMode` is set to `external`.
- `is_online`: Boolean indicating whether the Event is online.
- [`joinMode`](https://docs.joinmobilizon.org/contribute/activity_pub/#joinmode): `[free, restricted, invite, external]` default is `free`.
- [`location`](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-location): The subkey [`address`](https://schema.org/address) is accepted, both as [`PostalAddress`](https://schema.org/PostalAddress) and pure text.
- [`maximumAttendeeCapacity`](https://docs.joinmobilizon.org/contribute/activity_pub/#maximumattendeecapacity)
- [`mentions`](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-mentions)
- `metadata`: This is a list that can contain items. TODO.
- `participantCount`: [Not parsed at the moment](https://framagit.org/framasoft/mobilizon/-/issues/1412)
- [`repliesModerationOption`](https://docs.joinmobilizon.org/contribute/activity_pub/#repliesModerationOption)
- `remainingAttendeeCapacity`: [Not parsed at the moment](https://framagit.org/framasoft/mobilizon/-/issues/1412)
- [`tag`](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-tag)
- `timezone`
- `url`: [Documentation](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-url) - Note: `url` was added to the list as it was referenced in the text but not explicitly listed in the initial set.
### Not used
- [`url`](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-url): internally Mobilizon uses the `id` as URL.
### To Test:
### Handling of visibility, comments and discoverability
- If `https://www.w3.org/ns/activitystreams#Public` is not in `to` it will be treated as `unlisted`, else as `public`. This are the only options for remote events, even though internally Mobilizon supports `[public, unlisted, restricted, private]`.
- For comments to be enabled within Mobilizon either [`commentsEnabled`](https://docs.joinpeertube.org/api/activitypub) must be `true` or `repliesModerationOption` must be set to `allow_all`. `repliesModerationOption` is more important. If none is of both is passed replies will be disabled.
- When the `attributedTo` (or if `attributedTo` is not set, but `actor` is set) contains an `Actor` of type `Person` the remote `Event` will not be listed and searchable.
- If `timezone` is not defined Mobilizon might calculate the timezone via the `location`.
### Attachment/Banner-image handling
Mobilizon currently expects all images to by within `attachment` and to be an `Object` of type `Document`. It first looks for an object where the `name` is equal to `Banner`. If that is not found it uses ´attachment[0]`.
## Gancio
**Last uptaded**: 2024-01-20
### Required
- `id`: even though Gancio currently does not [list it as required in its source code](https://framagit.org/les/gancio/-/blob/master/server/federation/events.js?ref_type=heads#L19), there will be an error without out it.
- [`name`](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-name): The events title.
- [`startTime`](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-startTime)
### Optional
- [`attachment`](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-attachment) Only the first one is used as a banner image, all others are ignored, see below.
- [`content`](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-content) `contentMap` is currently not supported by Gancio.
- [`endTime`](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-endTime)
- [`location`](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-location): The subkey [`address`](https://schema.org/address) is accepted, both as [`PostalAddress`](https://schema.org/PostalAddress) and pure text. For `PostalAddress` only `streetAddress`, `addressLocality`, and `addressCountry` are used.
- [`summary`](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-summary) The summary is only used when no content is supplied.
### Not used
- `attributedTo`/`actor`: Gancio does not support fetching event other than by receiving a `Create` or `Update` activity (TODO: what about `Announce`), the actor is always just fetched from the activity, not the object within.
### Handling of visibility
Currently Gancio does not seem to handle any visibility or replies-policy options. It sets all remote events it received to the internal `is_visible` to `true`.
### Banner image
Gancio takes the first `attachment` of the `Event` object as the banner image of the event. It optionally supports [`name`](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-name) as the alternative text and [`focalPoint`](https://docs.joinmastodon.org/spec/activitypub/#focalPoint).
## Plemora
**Last uptaded**: 2024-01-20
**Information sources**: Plemora has a open [Pull Request towards Mobilizon compatible events](https://git.pleroma.social/pleroma/pleroma/-/merge_requests/3955/diffs) which Rebased (a fork of Plemora) has already merged.
### Required
This probably has a lot of errors still. [Source Code](https://git.pleroma.social/pleroma/pleroma/-/blob/b1a06c394736be833f8220a5ec3d5d2702d9519c/lib/pleroma/web/activity_pub/object_validators/event_validator.ex).
- `id`: even though Gancio currently does not [list it as required in its source code](https://framagit.org/les/gancio/-/blob/master/server/federation/events.js?ref_type=heads#L19), there will be an error without out it.
- [`name`](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-name): The events title.
- [`startTime`](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-startTime)
- [`endTime`](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-endTime)
### Optional
- [`joinMode`](https://docs.joinmobilizon.org/contribute/activity_pub/#joinmode): `[free, restricted, invite, external]` default is `free`.
- [`location`](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-location): The subkey [`address`](https://schema.org/address) is accepted, but currently ony as [`PostalAddress`](https://schema.org/PostalAddress) with the fields `postalCode`, `addressRegion`, `streetAddress`, `addressCountry` and `addressLocality`.
### Handling of visibility
Does not seem to be handled.