{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$defs": {
    "ResolvedHandle": {
      "type": "object",
      "properties": {
        "ref": {
          "type": "string"
        },
        "refStability": {
          "enum": [
            "stable",
            "ephemeral"
          ]
        },
        "targetKind": {
          "$ref": "#/$defs/TargetKind"
        }
      },
      "additionalProperties": false,
      "required": [
        "ref",
        "refStability",
        "targetKind"
      ]
    },
    "TargetKind": {
      "anyOf": [
        {
          "enum": [
            "text",
            "node",
            "list",
            "comment",
            "trackedChange",
            "table",
            "tableCell",
            "tableOfContents",
            "section",
            "sdt",
            "field"
          ]
        },
        {
          "type": "string",
          "pattern": "^ext:.+$"
        }
      ]
    },
    "CommentAddress": {
      "type": "object",
      "properties": {
        "kind": {
          "const": "entity"
        },
        "entityType": {
          "const": "comment"
        },
        "entityId": {
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "kind",
        "entityType",
        "entityId"
      ]
    },
    "TextTarget": {
      "type": "object",
      "properties": {
        "kind": {
          "const": "text"
        },
        "segments": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/TextSegment"
          },
          "minItems": 1
        },
        "story": {
          "$ref": "#/$defs/StoryLocator"
        },
        "coordinateSpace": {
          "$ref": "#/$defs/TextCoordinateSpace"
        }
      },
      "additionalProperties": false,
      "required": [
        "kind",
        "segments"
      ]
    },
    "TextSegment": {
      "type": "object",
      "properties": {
        "blockId": {
          "type": "string"
        },
        "range": {
          "$ref": "#/$defs/Range"
        }
      },
      "additionalProperties": false,
      "required": [
        "blockId",
        "range"
      ]
    },
    "Range": {
      "type": "object",
      "properties": {
        "start": {
          "type": "integer"
        },
        "end": {
          "type": "integer"
        }
      },
      "additionalProperties": false,
      "required": [
        "start",
        "end"
      ]
    },
    "StoryLocator": {
      "description": "Story scope. Defaults to document body when omitted. Use {kind:'story', storyType:'body'} for body, or other storyType values for headers, footers, footnotes, endnotes.",
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "kind": {
              "const": "story"
            },
            "storyType": {
              "const": "body"
            }
          },
          "additionalProperties": false,
          "required": [
            "kind",
            "storyType"
          ]
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "const": "story"
            },
            "storyType": {
              "const": "headerFooterSlot"
            },
            "section": {
              "$ref": "#/$defs/SectionAddress"
            },
            "headerFooterKind": {
              "enum": [
                "header",
                "footer"
              ]
            },
            "variant": {
              "enum": [
                "default",
                "first",
                "even"
              ]
            },
            "resolution": {
              "enum": [
                "effective",
                "explicit"
              ]
            },
            "onWrite": {
              "enum": [
                "materializeIfInherited",
                "editResolvedPart",
                "error"
              ]
            }
          },
          "additionalProperties": false,
          "required": [
            "kind",
            "storyType",
            "section",
            "headerFooterKind",
            "variant"
          ]
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "const": "story"
            },
            "storyType": {
              "const": "headerFooterPart"
            },
            "refId": {
              "type": "string"
            }
          },
          "additionalProperties": false,
          "required": [
            "kind",
            "storyType",
            "refId"
          ]
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "const": "story"
            },
            "storyType": {
              "const": "footnote"
            },
            "noteId": {
              "type": "string"
            }
          },
          "additionalProperties": false,
          "required": [
            "kind",
            "storyType",
            "noteId"
          ]
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "const": "story"
            },
            "storyType": {
              "const": "endnote"
            },
            "noteId": {
              "type": "string"
            }
          },
          "additionalProperties": false,
          "required": [
            "kind",
            "storyType",
            "noteId"
          ]
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "const": "story"
            },
            "storyType": {
              "const": "textbox"
            },
            "textboxId": {
              "type": "string"
            }
          },
          "additionalProperties": false,
          "required": [
            "kind",
            "storyType",
            "textboxId"
          ]
        }
      ]
    },
    "SectionAddress": {
      "type": "object",
      "properties": {
        "kind": {
          "const": "section"
        },
        "sectionId": {
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "kind",
        "sectionId"
      ]
    },
    "TextCoordinateSpace": {
      "enum": [
        "visible",
        "tracked"
      ]
    },
    "CommentTrackedChangeLink": {
      "type": "object",
      "properties": {
        "trackedChange": {
          "const": true
        },
        "trackedChangeId": {
          "type": "string"
        },
        "trackedChangeType": {
          "enum": [
            "insertion",
            "deletion",
            "replacement",
            "formatting",
            "move",
            "structural",
            "insert",
            "delete",
            "format"
          ]
        },
        "side": {
          "enum": [
            "inserted",
            "deleted",
            "source",
            "destination"
          ]
        },
        "trackedChangeText": {
          "type": "string"
        },
        "insertedText": {
          "type": "string"
        },
        "deletedText": {
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "trackedChange",
        "trackedChangeId",
        "trackedChangeType"
      ]
    },
    "PageInfo": {
      "type": "object",
      "properties": {
        "limit": {
          "type": "integer",
          "minimum": 0
        },
        "offset": {
          "type": "integer",
          "minimum": 0
        },
        "returned": {
          "type": "integer",
          "minimum": 0
        }
      },
      "additionalProperties": false,
      "required": [
        "limit",
        "offset",
        "returned"
      ]
    }
  },
  "operationId": "comments.list",
  "schemas": {
    "input": {
      "type": "object",
      "properties": {
        "includeResolved": {
          "type": "boolean",
          "description": "When true, includes resolved comments in results. Default: false."
        },
        "limit": {
          "type": "integer",
          "description": "Maximum number of comments to return."
        },
        "offset": {
          "type": "integer",
          "description": "Number of comments to skip for pagination."
        }
      },
      "additionalProperties": false
    },
    "output": {
      "type": "object",
      "properties": {
        "evaluatedRevision": {
          "type": "string"
        },
        "total": {
          "type": "integer",
          "minimum": 0
        },
        "items": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "handle": {
                "$ref": "#/$defs/ResolvedHandle"
              },
              "address": {
                "$ref": "#/$defs/CommentAddress"
              },
              "externalId": {
                "type": "string",
                "description": "Caller-owned durable integration id, distinct from the Word-compatible comment id."
              },
              "metadata": {
                "type": "object",
                "additionalProperties": true,
                "description": "Caller-owned JSON metadata persisted with the comment."
              },
              "importedId": {
                "type": "string"
              },
              "rawOoxmlId": {
                "type": "string",
                "description": "Durable raw OOXML source identity: the comment's w:id exactly as it appears in comments.xml. Surfaced for every catalog-backed comment, even when commentId already equals it on a clean import. Omitted for synthetic comments that never had a comments.xml carrier."
              },
              "rawOoxmlOccurrenceIndex": {
                "type": "number",
                "description": "Zero-based source occurrence among comments that share the same rawOoxmlId in comments.xml. Present only for duplicate raw OOXML ids."
              },
              "parentCommentId": {
                "type": "string"
              },
              "trackedChangeParentId": {
                "type": "string",
                "description": "SuperDoc logical tracked-change id when the comment anchor sits wholly inside exactly one active tracked change. Derived on read."
              },
              "trackedChangeThreadParentId": {
                "type": "string",
                "description": "SuperDoc logical tracked-change id whose review conversation this comment explicitly belongs to. Persisted provenance; never inferred from anchor overlap."
              },
              "trackedChangeSide": {
                "enum": [
                  "inserted",
                  "deleted",
                  "source",
                  "destination"
                ],
                "description": "Which side of the surrounding tracked change the comment anchor sits on."
              },
              "text": {
                "type": "string"
              },
              "isInternal": {
                "type": "boolean"
              },
              "status": {
                "enum": [
                  "open",
                  "resolved"
                ]
              },
              "target": {
                "$ref": "#/$defs/TextTarget"
              },
              "anchoredText": {
                "type": "string"
              },
              "createdTime": {
                "type": "number"
              },
              "creatorName": {
                "type": "string"
              },
              "creatorId": {
                "type": "string"
              },
              "creatorEmail": {
                "type": "string"
              },
              "creatorImage": {
                "type": "string"
              },
              "trackedChange": {
                "type": "boolean"
              },
              "trackedChangeType": {
                "enum": [
                  "insertion",
                  "deletion",
                  "replacement",
                  "formatting",
                  "move",
                  "structural",
                  "insert",
                  "delete",
                  "format"
                ]
              },
              "trackedChangeDisplayType": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "trackedChangeStory": {
                "oneOf": [
                  {
                    "$ref": "#/$defs/StoryLocator"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "trackedChangeAnchorKey": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "trackedChangeText": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "insertedText": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "deletedText": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "trackedChangeLink": {
                "oneOf": [
                  {
                    "$ref": "#/$defs/CommentTrackedChangeLink"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            },
            "additionalProperties": false,
            "required": [
              "id",
              "handle",
              "address",
              "status"
            ]
          }
        },
        "page": {
          "$ref": "#/$defs/PageInfo"
        }
      },
      "additionalProperties": false,
      "required": [
        "evaluatedRevision",
        "total",
        "items",
        "page"
      ]
    }
  }
}