{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "imports-v2/document_comments.json",
  "title": "Document comments",
  "description": "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.",
  "type": "object",
  "properties": {
    "external_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 512,
      "description": "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."
    },
    "document_ref": {
      "type": "string",
      "minLength": 1,
      "maxLength": 512,
      "x-ref": "documents",
      "description": "The document the comment is in. Give the external_id of a `documents` record of the package."
    },
    "text": {
      "type": "object",
      "properties": {
        "format": {
          "type": "string",
          "enum": [
            "plain_text",
            "markdown",
            "html"
          ]
        },
        "text": {
          "type": "string"
        }
      },
      "required": [
        "format",
        "text"
      ],
      "additionalProperties": false,
      "x-link-tokens": [
        {
          "scheme": "attachment",
          "resource": "attachments"
        },
        {
          "scheme": "card",
          "resource": "cards"
        },
        {
          "scheme": "document",
          "resource": "documents"
        }
      ],
      "description": "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."
    },
    "parent_ref": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "maxLength": 512,
      "x-ref": "document_comments",
      "description": "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."
    },
    "resolved_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?(Z|[+-]\\d{2}:\\d{2})$",
      "description": "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."
    },
    "updated_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?(Z|[+-]\\d{2}:\\d{2})$",
      "description": "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."
    },
    "author_ref": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "maxLength": 512,
      "x-ref": "users",
      "description": "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": {
      "type": "string",
      "format": "date-time",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?(Z|[+-]\\d{2}:\\d{2})$",
      "description": "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.",
      "x-default-text": "source.exported_at of the manifest"
    }
  },
  "required": [
    "external_id",
    "document_ref",
    "text"
  ],
  "additionalProperties": false,
  "allOf": [
    {
      "if": {
        "properties": {
          "parent_ref": {
            "type": "string"
          }
        },
        "required": [
          "parent_ref"
        ]
      },
      "then": {
        "properties": {
          "resolved_at": {
            "type": "null"
          }
        }
      }
    }
  ]
}