DocumentationServerComments

Cell Comments

Cell comments in Jspreadsheet Server are a worksheet property: a map keyed by cell name whose values are either a plain text note or an array of comment entries (a thread). The server has no comment-specific behavior beyond input validation. Comments are read, changed, synchronized and persisted through the same pipeline as every other spreadsheet 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.

When comments are submitted through the REST API, the server 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. Like any other change, it is applied to the live server-side instance of the document, stamped with the next revision, and broadcast over WebSocket to every client connected to that document, so all collaborators see new or edited comments in real time. There is no separate channel or storage for comments.

Persistence

Comments are persisted through your adapter's change handler as part of the normal per-operation persistence flow. In the MongoDB adapter, for example, each setComments operation updates the spreadsheet.worksheets[<index>].comments.<cell> fields of the document, 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. A setComments change passes through your beforeChange hook like any other operation, and reading comments requires permission to load the document. In the reference wiring, setComments is not among the owner-only methods, so any user with editor access can add or change comments.

REST Routes

The API exposes comments per worksheet:

  • 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.

Parameters and examples are on the REST reference page linked below.

Related pages