ActivityPub Personal Places

Introduction

Geosocial software lets people sharing information about their relationship with places. Activity Streams 2.0 defines a Place object type for representing places.

Places can be defined globally as part of a geographical vocabulary. For example, places.pub is a server that provides places from the OpenStreetMap service in ActivityPub format. These places are a shared resource for all ActivityPub users.

Some geosocial software lets users define personal places, like "Home", "Work", "School", "Favourite Tree" or "Mom's House". These places may be identical to places defined in a public vocabulary, with different and more personal names, images, and descriptions, or they may be distinct from any publicly-defined place.

This document defines how personal places can be created and managed ActivityPub.

User stories

This specification addresses the following user stories.

As an ActivityPub user, I'd like to create a place that is important in my own life, so that I can check in, share, comment on, or otherwise engage with the place.

As an ActivityPub user, I want to read the information about a friend's personal place, so that I can understand where she is checking into and what it means to her.

As an ActivityPub user, I want to edit a place, so I can update its location or metadata.

As an ActivityPub user, I want to delete a place I created, so it's no longer visible to anyone.

As an ActivityPub user, I want to get a list of the places that I've created, so I can find one that I'm interested in.

Creating a Place

To create a new place, the actor uses the ActivityPub social API. The client posts a Create activity to their own outbox, with a Place object as the object property.

In this example, the user is creating a place representing their home. They have used the lat/lon for the Mont Royal metro station in Montreal, and used the radius property to show that the place is within 500m of that landmark. A geosocial UI might show a circle for the range where the place might be.

          {
            "@context": "https://www.w3.org/ns/activitystreams",
            "type": "Create",
            "to": "as:Public",
            "summary": "Evan created the personal place 'Home'"
            "object": {
              "type": "Place",
              "name": "Home",
              "summary": "My home in Plateau Mont-Royal",
              "lat": 45.5245985,
              "lon": 73.5816468,
              "radius": 500,
              "units": "m"
            }
          }

In this example, the user creates a place representing their workplace. They restrict access to their followers. Because they work at the Ecto Coworking, they use the alsoKnownAs property to note that these are the same place.

          {
            "@context": "https://www.w3.org/ns/activitystreams",
            "type": "Create",
            "to": "https://social.example/user/evan/followers",
            "summary": "Evan created the personal place 'Work'"
            "object": {
              "type": "Place",
              "name": "Work",
              "latitude": 45.52682,
              "longitude": -73.58012,
              "alsoKnownAs": "https://places.pub/node/3313351996"
            }
          }

Reading a Place

Like other ActivityPub objects, Place objects can be read using the id property.

In this example, the user has received a place id https://social.example/users/evan/place/33. They use an HTTP GET request to fetch the ActivityPub Place object.

          GET /users/evan/place/33 HTTP/1.1
          Host: social.example

          200 OK
          Content-Type: application/activity+json

          {
            "@context": "https://www.w3.org/ns/activitystreams",
            "id": "https://social.example/users/evan/place/33",
            "type": "Place",
            "name": "Home",
            "summary": "My home in Plateau Mont-Royal",
            "lat": 45.5245985,
            "lon": 73.5816468,
            "radius": 500,
            "units": "m",
            "to": "as:Public",
            "attributedTo": "https://social.example/users/evan"
          }

Editing a Place

To edit a place, the actor uses the ActivityPub social API. The client posts a Update activity to their own outbox, with an existing Place object as the object property.

In this example, the user is changing the description of a place they have previously created, and adding an image (managed separately).

          {
            "@context": "https://www.w3.org/ns/activitystreams",
            "type": "Update",
            "to": "as:Public",
            "summary": "Evan updated the personal place 'Home'"
            "object": {
              "id": "https://social.example/users/evan/place/33",
              "summary": "My house in Montreal",
              "image": {
                "type": "Link",
                "name": "Front view of my house",
                "href": "https://files.social.example/11837.jpg"
              }
            }
          }

Deleting a Place

To delete a place, the actor uses the ActivityPub social API. The client posts a Delete activity to their own outbox, with an existing Place object as the object property.

In this example, the user deletes the https://social.example/users/evan/place/33.

          {
            "@context": "https://www.w3.org/ns/activitystreams",
            "type": "Delete",
            "to": "as:Public",
            "summary": "Evan deleted the personal place 'Home'"
            "object": "https://social.example/users/evan/place/33"
          }

In this example, the user has received a place id https://social.example/users/evan/place/33. They use an HTTP GET request to fetch the ActivityPub Place object. Because it has been deleted, only a Tombstone object is returned.

          GET /users/evan/place/33 HTTP/1.1
          Host: social.example

          410 Gone
          Content-Type: application/activity+json

          {
            "@context": "https://www.w3.org/ns/activitystreams",
            "id": "https://social.example/users/evan/place/33",
            "type": "Tombstone",
            "formerType": "Place"
          }

Listing Personal Places

The actor's personal places can be listed in an ActivityPub OrderedCollection. The collection is ordered in reverse chronological order, with the newest places first.

The actor object can have a places property to indicate the user's places.

The collection can have a placesOf property to the actor whose places these are.

In this example, an actor has an associated collection of places.

          {
            "@context": [
              "https://www.w3.org/ns/activitystreams",
              "https://swicg.github.io/geosocial/geosocial"
            ],
            "type": "Person",
            "id": "https://social.example/user/evan",
            "inbox": "https://social.example/user/evan/inbox",
            "outbox": "https://social.example/user/evan/outbox",
            "following": "https://social.example/user/evan/following",
            "followers": "https://social.example/user/evan/followers",
            "liked": "https://social.example/user/evan/liked",
            "places": "https://social.example/user/evan/places",
          }

This is a user's collection of places. It uses the placesOf property to declare its relationship to the user. One place is included with a brief embedded object; the other is included only as an URL.

          {
            "@context": [
              "https://www.w3.org/ns/activitystreams",
              "https://swicg.github.io/geosocial/geosocial"
            ],
            "type": "OrderedCollection",
            "id": "https://social.example/user/evan/places",
            "to": "as:Public",
            "attributedTo": "https://social.example/user/evan",
            "placesOf": "https://social.example/user/evan",
            "totalItems": 2,
            "items": [
              {
                "type": "Place",
                "id": "https://social.example/user/evan/place/33",
                "name": "Home"
              },
              "https://social.example/user/evan/place/34"
            ]
          }

Terms

There are two new terms defined by this specification. The context document is at https://swicg.github.io/geosocial/geosocial.

places

URI:	`https://swicg.github.io/geosocial/geosocial#places` `geosocial:places` `places`
Notes:	The property value is an `OrderedCollection` of `Place` objects.
Domain:	`Object` (an ActivityPub Actor)
Range:	`OrderedCollection`
Functional:	`true`

placesOf

URI:	`https://swicg.github.io/geosocial/geosocial#placesOf` `geosocial:placesOf` `placesOf`
Notes:	The property value is an ActivityPub actor for which the collection is the `places` collection.
Domain:	`OrderedCollection`
Range:	`Object` (an ActivityPub Actor)
Functional:	`true`