CommentList

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/antwork-io/json-schema/antwork-io-comment-list-schema.json",
  "title": "CommentList",
  "x-generated": "2026-11-01",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/antwork-io-openapi.json#/components/schemas/CommentList",
  "type": "object",
  "required": [
    "postId",
    "platform",
    "accountId",
    "comments",
    "nextCursor",
    "reply"
  ],
  "properties": {
    "postId": {
      "type": "string"
    },
    "platform": {
      "type": "string"
    },
    "accountId": {
      "type": "string"
    },
    "comments": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Comment"
      },
      "description": "Newest first; replies oldest first."
    },
    "nextCursor": {
      "type": [
        "string",
        "null"
      ],
      "description": "Pass as `cursor` for the next page. Null on networks that answer with the whole thread."
    },
    "reply": {
      "type": "object",
      "required": [
        "allowed",
        "topLevel"
      ],
      "properties": {
        "allowed": {
          "type": "boolean"
        },
        "topLevel": {
          "type": "boolean",
          "description": "A reply to the post itself (no `commentId`) is allowed."
        },
        "reason": {
          "type": "string",
          "description": "Why replies are not allowed, as a stable code."
        },
        "message": {
          "type": "string"
        }
      }
    },
    "olderThanSearchWindow": {
      "type": "boolean",
      "description": "X: the post is older than the 7 days recent search reaches, so earlier replies are missing from `comments`. Present only when true."
    },
    "note": {
      "type": "string",
      "description": "Why the list may be incomplete, in plain English. Present with `olderThanSearchWindow`."
    },
    "cachedAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "X: served from the 10-minute cache; when it was read from the network."
    }
  },
  "$defs": {
    "Comment": {
      "type": "object",
      "required": [
        "id",
        "parentId",
        "author",
        "text",
        "createdAt",
        "canReply"
      ],
      "description": "A comment on a published post, as the network returned it (`src/lib/comments/types.ts`). Nothing is stored.",
      "properties": {
        "id": {
          "type": "string",
          "description": "The network's id; pass it back as `commentId` to reply."
        },
        "parentId": {
          "type": [
            "string",
            "null"
          ],
          "description": "The comment this one answers; null for a comment on the post."
        },
        "author": {
          "type": "object",
          "required": [
            "name",
            "handle",
            "avatarUrl"
          ],
          "properties": {
            "name": {
              "type": "string",
              "description": "Empty where the network does not share it (LinkedIn members)."
            },
            "handle": {
              "type": [
                "string",
                "null"
              ]
            },
            "avatarUrl": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        },
        "text": {
          "type": "string"
        },
        "createdAt": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "likeCount": {
          "type": "integer"
        },
        "replies": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Comment"
          },
          "description": "One level: deeper replies are flattened under their top-level comment."
        },
        "canReply": {
          "type": "boolean"
        },
        "url": {
          "type": [
            "string",
            "null"
          ]
        },
        "mention": {
          "type": "string",
          "description": "Mastodon: start a reply with this for the author to be notified."
        },
        "isOwn": {
          "type": "boolean",
          "description": "Written by the connected account itself."
        }
      }
    }
  }
}