Skip to content

Add clipped flag to annotations doc #2871

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 10, 2025
Merged

Add clipped flag to annotations doc #2871

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 41 additions & 14 deletions src/pages/docs/messages/annotations.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,8 @@ A given client can contribute to the summary only once per annotation type.
{
"reactions:flag.v1": {
"total": 3,
"clientIds": ["client1", "client2", "client3"]
"clientIds": ["client1", "client2", "client3"],
"clipped": false
}
}
```
Expand All @@ -95,11 +96,13 @@ Deleting an annotation removes the `clientId` from the list of clients that cont
"categories:distinct.v1": {
"important": {
"total": 2,
"clientIds": ["client1", "client3"]
"clientIds": ["client1", "client3"],
"clipped": false
},
"urgent": {
"total": 3,
"clientIds": ["client1", "client2", "client3"]
"clientIds": ["client1", "client2", "client3"],
"clipped": false
}
}
}
Expand All @@ -120,11 +123,13 @@ Deleting an annotation removes the `clientId` from the list of clients that cont
"status:unique.v1": {
"important": {
"total": 2,
"clientIds": ["client1", "client3"]
"clientIds": ["client1", "client3"],
"clipped": false
},
"urgent": {
"total": 1,
"clientIds": ["client2"]
"clientIds": ["client2"],
"clipped": false
}
}
}
Expand All @@ -151,15 +156,19 @@ Deleting an annotation removes all contributions made by that `clientId` for tha
"client1": 3,
"client2": 2
},
"totalUnidentified": 2
"totalUnidentified": 2,
"clipped": false,
"totalClientIds": 2
},
"option-b": {
"total": 4,
"clientCounts": {
"client1": 2,
"client3": 1
},
"totalUnidentified": 1
"totalUnidentified": 1,
"clipped": false,
"totalClientIds": 2
}
}
}
Expand Down Expand Up @@ -350,26 +359,31 @@ The summary will be included in a `summary` field nested within the message's `a
},
"reactions:flag.v1": {
"total": 3,
"clientIds": ["client1", "client2", "client3"]
"clientIds": ["client1", "client2", "client3"],
"clipped": false
},
"categories:distinct.v1": {
"important": {
"total": 2,
"clientIds": ["client1", "client3"]
"clientIds": ["client1", "client3"],
"clipped": false
},
"urgent": {
"total": 3,
"clientIds": ["client1", "client2", "client3"]
"clientIds": ["client1", "client2", "client3"],
"clipped": false
}
},
"status:unique.v1": {
"important": {
"total": 2,
"clientIds": ["client1", "client3"]
"clientIds": ["client1", "client3"],
"clipped": false
},
"urgent": {
"total": 1,
"clientIds": ["client2"]
"clientIds": ["client2"],
"clipped": false
}
},
"voting:multiple.v1": {
Expand All @@ -379,21 +393,34 @@ The summary will be included in a `summary` field nested within the message's `a
"client1": 3,
"client2": 2
},
"totalUnidentified": 2
"totalUnidentified": 2,
"clipped": false,
"totalClientIds": 2
},
"option-b": {
"total": 4,
"clientCounts": {
"client1": 2,
"client3": 1
},
"totalUnidentified": 1
"totalUnidentified": 1,
"clipped": false,
"totalClientIds": 2
}
}
}
```
</Code>

### Large summaries <a id="large-summaries"/>

If many clients publish the same annotation to the same message, the list of client IDs in that annotation summary will get clipped in order to keep the event size within the maximum message size.

When a summary is clipped:
- The `total` property shows the total number of annotations as expected, but the `clientIds` property will contain only a partial list of client IDs.
- The `clipped` property is set to `true`.
- For the `multiple` annotation type, use the `totalClientIds` property to determine the total number of clients that have published the annotation. For the other annotation types this is equal to `total`.

## Subscribe to individual annotation events <a id="individual-annotations"/>

It is also possible to subscribe to individual annotation events, rather than annotation summaries. These are the emitted when [publishing](#publish) or [deleting](#delete) an annotation.
Expand Down