ServerDocumentationComments

Cell Comments

Cell comments are a worksheet property. Apart from input validation, the server has no comment-specific behavior: comments go through the same pipeline as every other operation and are exposed over the REST API.

Documentation

Data Model

Each worksheet holds a comments object keyed by A1-style cell names. The value for a cell is one of:

  • A string: a plain note attached to the cell.
  • An array of comment objects: a thread. Each entry accepts the following properties:
Property Type Description
comments string, required The comment text.
date string, required The comment date.
user_id unsigned integer, optional Identifier of the author.
name string, optional Display name of the author.
edited boolean, optional Kept only when true.

The REST API validates this shape and rejects the request with a descriptive error when a cell name is invalid or an entry does not match the types above. Cell names must be in A1 notation (up to three letters, row number up to 1,000,000).

Synchronization

Changing comments produces a setComments operation. It is applied to the server-side instance, stamped with the next revision and broadcast over WebSocket to every client connected to the document. There is no separate channel or storage for comments.

Persistence

Comments are persisted through your adapter's change handler, per operation. In the MongoDB adapter, for example, each setComments operation updates the spreadsheet.worksheets[<index>].comments.<cell> fields, and the comments map is re-persisted after structural operations (row and column inserts, deletes and moves) so it stays aligned with the moved cells.

Access Control

There are no comment-specific permissions. setComments passes through your beforeChange hook, and reading comments requires permission to load the document. In the reference wiring, setComments is not owner-only, so any user with editor access can add or change comments.

REST Routes

  • GET /api/<guid>/<worksheet>/comments: all comments of the worksheet.
  • GET /api/<guid>/<worksheet>/comments/<cells>: comments for specific cells; accepts a comma-separated list (A1,B3) and ranges (D1:D4).
  • POST /api/<guid>/<worksheet>/comments: create or update comments.

Related pages