Document comments
A comment in the comments of a document, such as a question about a definition. Comments are grouped in threads: a comment without parent_ref starts a thread, and the replies of a thread are listed under it in the order they were written. A thread can be resolved with resolved_at on its first comment. A comment is about the whole document; pointing a comment at a part of the text is not supported.
A record of this entity needs records of other entities in the package: Documents.
Files in the package
List every file of this entity in resource_files of the manifest, with "resource": "document_comments". An entity can have any number of files. See Bundle format.
[
{
"resource": "document_comments",
"path": "resources/document_comments.json"
}
]Fields
| Field | Type | Required | Description |
|---|---|---|---|
external_id | string (ExternalId) | Yes | Your own identifier of the record, for example k-mrr, unique within the resource across all of its files and case sensitive. Other records refer to this one by it.Constraints: 1–512 characters. |
document_ref | Ref<documents> refers to Documents | Yes | The document the comment is in. Give the external_id of a documents record of the package. |
text | RichText | Yes | What the comment says, for example {"format": "markdown", "text": "Should **ARR** include trials?"}. Plain text, Markdown and HTML are accepted; the text is kept as Markdown. Links to cards and documents of the package (card://<external_id>, document://<external_id>) become links. |
author_ref | Ref<users>? refers to Users | No | The user who wrote the comment, shown with their name and avatar, by the external_id of a users record, for example u-ava. Left out or null, the comment is shown as written by the user who runs the import. |
created_at | Timestamp | No | When the comment was written, for example 2026-01-12T09:30:00Z. The comment shows this time, and comments and threads are ordered by it. Left out, the export time is used.Constraints: RFC 3339 with a time zone. Default: |
parent_ref | Ref<document_comments>? refers to Document comments | No | The comment this one answers; absent or null starts a new thread. It must be a comment of the same document. A reply to a reply joins the same thread: a thread is one list of comments, not a tree. Rule: A comment of the same document. |
resolved_at | Timestamp? | No | When the thread was resolved. Give it only on the first comment of a thread, the one without parent_ref. A resolved thread is marked "Marked as resolved" and is listed under the Resolved filter of the document's comments instead of Open.Constraints: RFC 3339 with a time zone. Rule: Only when parent_ref is null. |
updated_at | Timestamp? | No | When the comment was last edited; not earlier than created_at. Given, the comment is marked "(edited)"; the time itself is not shown. Leave it out for a comment that was never edited.Constraints: RFC 3339 with a time zone. Rule: Not earlier than created_at. |
References
Referenced by
- Document comments:
parent_ref
Document comments
Refers to
author_ref→ Usersdocument_ref→ Documentsparent_ref→ Document comments
Show on the entity map
Example
A record of this entity:
{
"external_id": "dc-glossary-1",
"document_ref": "d-glossary",
"text": {
"format": "plain_text",
"text": "Should the glossary also define \"active account\"?"
},
"author_ref": "u-sofia",
"created_at": "2026-03-10T09:00:00Z"
}Rules
- resolved_at only when parent_ref is null or absent.
- parent_ref builds a tree; no record can be its own ancestor.
Related entities
Attachments, Documents, Users
JSON Schema
document_comments.json
