DataSync built-in types

Users, channels, and memberships are DataSync's built-in classes. A user and a channel are entities. A membership is a relationship linking a channel to a user. Everything in the Data model applies to them: payloads, ETags, time-to-live (TTL), events, and access control.

Users

A user is an entity of the built-in Global User entity class, which PubNub seeds at version 1. Creating a user requires only entityClassVersion. The id is optional, and DataSync generates one if you omit it.

The user endpoints are Get users, Get user, Create user, Update user, Patch user, and Delete user.

User fields:

Field	Purpose
id	The user ID
createdAt	Creation timestamp
updatedAt	Last modification timestamp
eTag	Optimistic concurrency marker
status	A free-form application lifecycle string, 1 to 100 characters
expiresAt	Expiry timestamp. Inherits the Global class's 2,592,000 seconds (30 days) TTL by default
entityClass	The name of the entity class, User unless you've extended it
entityClassVersion	The version of the User class this instance pins to
entityClassLevel	Whether that class is Global or SubKey (keyset-level)
payload	Your application data

The built-in User class declares two properties: name at /payload/name and type at /payload/type, both strings, nullable, fully filterable, and in the __default__ projection. Any additional payload fields are stored as-is but aren't indexed.

The Global User class can't be changed. To add your own fields, define a class on your keyset that extends the Global User class through an extends reference. Your subclass inherits name and type automatically, and you only declare the fields you're adding. See Class inheritance.

A user's id is the same identifier as the UUID used elsewhere on PubNub for messaging and Presence. They aren't the same stored record: DataSync keeps its own entity, separate from Presence and Pub/Sub state. A UUID works for messaging and Presence whether or not a matching entity exists in DataSync. Creating, updating, or deleting the entity has no effect on that UUID's ability to publish, subscribe, or appear in Presence.

Channels

A channel is an entity of the built-in Global Channel entity class, with the same field shape as a user. A channel entity stores data about a channel your app uses for messaging, for example a display name or a category.

The channel endpoints are Get channels, Get channel, Create channel, Update channel, Patch channel, and Delete channel.

A channel entity is not a pub/sub channel

Creating a channel entity doesn't create or configure the underlying Pub/Sub channel, and a channel does not need an entity for messaging to work. The entity holds metadata. The Pub/Sub and Presence channel carries messages and subscribers. They share an ID but have separate lifecycles.

Memberships

A membership is a relationship of the built-in Global Membership relationship class, linking a channel and a user. The Membership class is many-to-many, so a user can belong to many channels and a channel can have many members.

The membership endpoints are Get memberships, Get membership, Create membership, Update membership, Patch membership, and Delete membership.

Membership fields, in addition to the standard system fields:

Field	Purpose
id	The membership's own identifier
channelId	The linked channel's ID (entity A)
userId	The linked user's ID (entity B)
relationshipClass	Always Membership, set by DataSync
relationshipClassVersion	The version of the Membership class this instance pins to
payload	Association data, for example a role

Creating a membership requires channelId, userId, and relationshipClassVersion. Both the channel and the user must already exist, or the request returns a 404. Only one membership can exist for a given channel and user, so a duplicate returns a 409.

Membership lists can be narrowed by user_id, by channel_id, or by both together, covering the two common questions: which channels a user belongs to, and who is a member of a channel. Refer to Get memberships.

Because the Membership class declares no properties and can't be extended, membership payload fields are never indexed. The built-in fields id, createdAt, updatedAt, and status are still filterable and sortable.

Real-time updates

Creating, updating, or deleting a user, channel, or membership can publish a DataSync event, the same way any other entity or relationship can. Events are off by default and enabled per class version, per keyset, in the Admin Portal.

A create event for a user publishes on that user's ID channel. Update and delete events also publish on the ID channels of every entity the user is linked to by a relationship. A membership event publishes on both the linked channel's and the linked user's ID channels, never on the membership's own ID channel.

To watch a user's memberships appear and disappear, subscribe to the user's ID channel, not to any membership ID. Refer to Events for the full routing model.

Access Manager tokens grant permissions on the same user and channel IDs you use here. Memberships are a separate datasync:memberships resource type, so granting access to a user or channel doesn't authorize creating, updating, or deleting memberships between them. Refer to DataSync access control.

Comparison with App Context

App Context	DataSync
User metadata with top-level name, email, profileUrl, externalId, custom	User entity with all application data inside payload
Channel metadata	Channel entity with data in payload
Membership with custom data	Membership relationship with payload
Optional Access Manager	Access Manager required
Set/delete events (message type 2)	Create/update/delete events (message type 5)

App Context keeps working, and there is no automatic migration of existing data to DataSync.