Comment

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/derive-to/json-schema/derive-to-comment-schema.json",
  "title": "Comment",
  "x-generated": "2026-11-05",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/derive-to-openapi.json#/components/schemas/Comment",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "artifact_id": {
      "type": "string",
      "description": "The artifact the comment is on."
    },
    "thread_id": {
      "type": "string",
      "description": "The thread this comment belongs to; equals id for the thread's root comment."
    },
    "base_version": {
      "type": "number",
      "description": "Artifact version this comment was anchored against."
    },
    "path": {
      "type": [
        "string",
        "null"
      ],
      "description": "File within a bundle the comment targets; null if not file-scoped."
    },
    "anchor": {
      "type": [
        "string",
        "null"
      ],
      "description": "Serialized text-quote or element anchor locating the comment; null if unanchored."
    },
    "body_md": {
      "type": "string",
      "description": "Comment body in Markdown; blanked when the comment is deleted."
    },
    "author": {
      "type": "string",
      "description": "Author's display name; \"anonymous\" for an anonymous poster."
    },
    "author_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "Stable id of the author: a user id, an agent id, or \"derive\" for an @Derive reply; null for anonymous or legacy rows."
    },
    "author_kind": {
      "type": "string",
      "enum": [
        "user",
        "agent",
        "anonymous"
      ],
      "description": "What kind of principal wrote it, from the recorded id."
    },
    "options": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "string"
      },
      "description": "On a question's root comment: the choices it offers. A reply (a choice or other words) answers it."
    },
    "resolution": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "at": {
          "type": "string"
        },
        "by": {
          "type": [
            "string",
            "null"
          ],
          "description": "The resolver's display name at the time."
        },
        "by_id": {
          "type": [
            "string",
            "null"
          ]
        },
        "by_kind": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "user",
            "agent",
            null
          ]
        },
        "version": {
          "type": [
            "number",
            "null"
          ],
          "description": "The version whose publish resolved the thread; null for a hand resolve."
        }
      },
      "required": [
        "at",
        "by",
        "by_id",
        "by_kind",
        "version"
      ],
      "description": "On a resolved thread's root: who settled it, when, and by which version."
    },
    "state": {
      "type": "string",
      "enum": [
        "open",
        "resolved",
        "outdated"
      ],
      "description": "Thread state: open, resolved, or outdated (the quoted text changed)."
    },
    "created_at": {
      "type": "string"
    },
    "anchored": {
      "type": "boolean",
      "description": "Whether the anchor still resolves against the current version (list only)."
    },
    "reactions": {
      "type": "object",
      "additionalProperties": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "description": "Emoji → list of reactor display names."
    },
    "edited": {
      "type": "boolean",
      "description": "True if the body was edited after posting."
    },
    "edited_at": {
      "type": [
        "string",
        "null"
      ],
      "description": "When the comment was last edited; null if never."
    },
    "deleted": {
      "type": "boolean",
      "description": "True if soft-deleted; the row stays but the body is blanked."
    },
    "mentions": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Mention"
      },
      "description": "Users or agents @mentioned in the comment body."
    }
  },
  "required": [
    "id",
    "artifact_id",
    "thread_id",
    "base_version",
    "path",
    "anchor",
    "body_md",
    "author",
    "author_kind",
    "state",
    "created_at"
  ],
  "$defs": {
    "Mention": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Id of the mentioned person or agent."
        },
        "name": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "name"
      ]
    }
  }
}