# Change Schema for Comments

## Introduction

Schemas are structured definitions that describe the format, rules, and relationships of data within a system. They ensure consistency and validate inputs. In the Beefree SDK, the **Change Schema** defines the structure for tracking changes in collaborative environments, particularly for managing comment threads within content blocks. These changes are recorded with associated metadata to support real-time collaboration, versioning, and user engagement. This documentation breaks down the schema’s types, payload structure, and practical usage to help you effectively implement comment-based interactions into your system.

### Schema Overview

This section summarizes the purpose and key characteristics of the Change Schema.

* **Schema Name**: Change
* **Purpose**: Tracks various types of comment-related actions such as creation, resolution, editing, or deletion.
* **Mandatory Fields**: `type`, `payload`
* **Restrictions**: Each change type defines its own required payload structure.
* **Related Schemas**:
  * `comment.schema.json` (for individual comment details)
  * `user.schema.json` (for user attribution and metadata)

### Structure Definition

Below is the JSON Schema definition and a detailed breakdown of each property.

#### JSON Schema (Simplified Overview)

```json
{
  "type": "object",
  "properties": {
    "change": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "NEW_COMMENT",
            "COMMENT_THREAD_RESOLVED",
            "COMMENT_THREAD_REOPENED",
            "COMMENT_EDITED",
            "COMMENT_DELETED"
          ]
        },
        "payload": {
          "type": "object"
        }
      },
      "required": ["type", "payload"]
    },
    "comments": {
      "type": "object",
      "additionalProperties": {
        "$ref": "comment.schema.json"
      }
    },
    "threadUsers": {
      "type": "object",
      "properties": {
        "contributors": {
          "type": "array",
          "items": {
            "$ref": "user.schema.json"
          }
        }
      }
    }
  },
  "required": ["change"]
}
```

### Field Descriptions

The following list displays the field descriptions along with their corresponding descriptions.

* **change.type**: Enumerates the type of action taken (e.g., new comment, resolution).
* **change.payload**: Contains the change-specific data. The structure varies based on `type`.
* **comments**: A mapping of `commentId` to its full comment object.
* **threadUsers.contributors**: Lists users involved in the comment thread.

### Usage Examples

Reference a practical example of the schema in the following code snippet.

#### Example: New Comment

```json
{
  "change": {
    "type": "NEW_COMMENT",
    "payload": {
      "commentId": "a2c555e4-72f7-4e7f-96cd-537e5eb2069c",
      "comment": {
        "content": "add new Text block and logo here!",
        "parentCommentId": null,
        "elementId": "73dcc71b-1ba7-458d-81b8-59ec54e534a5",
        "mentions": [],
        "responses": [],
        "timestamp": "2022-04-05T13:53:28.089Z",
        "author": {
          "userHandle": "0.6379069806343958",
          "username": "John Doe",
          "userColor": "#ff4400"
        }
      }
    }
  },
  "comments": {
    "a2c555e4-72f7-4e7f-96cd-537e5eb2069c": {
      "content": "add new Text block and logo here!",
      "parentCommentId": null,
      "elementId": "73dcc71b-1ba7-458d-81b8-59ec54e534a5",
      "mentions": [],
      "responses": [],
      "timestamp": "2022-04-05T13:53:28.089Z",
      "author": {
        "userHandle": "0.6379069806343958",
        "username": "John Doe",
        "userColor": "#ff4400"
      }
    }
  },
  "threadUsers": {
    "contributors": [
      {
        "userHandle": "0.6379069806343958",
        "username": "John Doe",
        "userColor": "#ff4400"
      }
    ]
  }
}
```

### Additional Considerations

Consider the following when working with the Change Schema:

* **Thread Management**: Leverage `parentCommentId` to group responses into threads.
* **User Attribution**: Use `userHandle` and `userColor` to personalize the UI.
* **Audit Logging**: This schema can support full history tracking and rollback features.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.beefree.io/beefree-sdk/data-structures/comments-schema/change-schema-for-comments.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.