# Comments Schema

## 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 **Comments Schema** defines the structure for storing comment threads tied to specific content elements within a template. This schema supports collaborative workflows such as feedback, review, and approval by linking user-generated comments to specific layout components via `elementId`. The host application may choose to manage these comments dynamically or store them statically within saved template versions.

### Schema Overview

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

* **Schema Name**: Comments
* **Purpose**: Stores user comments and threaded responses linked to specific layout elements within a template.
* **Mandatory Fields**: `content`, `elementId`, `timestamp`, `author`
* **Restrictions**: Each comment must be uniquely identified; threaded replies must reference a valid `parentCommentId`.
* **Related Schemas**:
  * `user.schema.json` (for comment authorship)
  * `element.schema.json` (via `elementId`)

### Structure Definition

Below is a generalized representation of the Comments Schema and its property definitions.

#### JSON Schema (Simplified Overview)

```json
{
  "type": "object",
  "patternProperties": {
    "^[a-z0-9-]{36}$": {
      "type": "object",
      "properties": {
        "content": { "type": "string" },
        "parentCommentId": { "type": ["string", "null"] },
        "elementId": { "type": "string" },
        "responses": {
          "type": "array",
          "items": { "type": "string" }
        },
        "timestamp": { "type": "string", "format": "date-time" },
        "author": {
          "type": "object",
          "properties": {
            "uid": { "type": "string" },
            "username": { "type": "string" },
            "userColor": { "type": "string" }
          },
          "required": ["uid", "username", "userColor"]
        },
        "isElementDeleted": { "type": "boolean" }
      },
      "required": ["content", "elementId", "timestamp", "author"]
    }
  }
}
```

### Field Descriptions

* **commentId**: A unique identifier (UUID) used as the key for each comment object.
* **content**: The text content of the comment.
* **parentCommentId**: If present, indicates that the comment is a reply within a thread.
* **elementId**: References the specific content element (e.g., a button or image) that the comment targets.
* **responses**: An array of comment IDs that are direct replies to the current comment.
* **timestamp**: ISO 8601 formatted timestamp indicating when the comment was created.
* **author**: Metadata for the user who posted the comment, including a unique user ID, display name, and color for UI purposes.
* **isElementDeleted**: A flag indicating whether the referenced content element has been removed from the layout.

### Usage Examples

The following is a real-world example of a two-level comment thread.

#### Example: Threaded Comments

```json
{
  "comments": {
    "aab0227f-766d-439d-b3d9-8bf7d04d551f": {
      "content": "Here is a comment",
      "parentCommentId": null,
      "elementId": "ab35241d-dd69-4980-9385-862fedd094e4",
      "responses": [
        "84f11738-a5a2-49db-956a-ae95b4d1db67"
      ],
      "timestamp": "2020-09-07T13:58:43.147Z",
      "author": {
        "uid": "my user id",
        "username": "US Person 2",
        "userColor": "#dddddd"
      },
      "isElementDeleted": false
    },
    "84f11738-a5a2-49db-956a-ae95b4d1db67": {
      "content": "Here is a second comment",
      "parentCommentId": "aab0227f-766d-439d-b3d9-8bf7d04d551f",
      "elementId": "ab35241d-dd69-4980-9385-862fedd094e4",
      "responses": [],
      "timestamp": "2020-09-07T13:59:51.954Z",
      "author": {
        "uid": "my user id 2",
        "username": "US Person 4",
        "userColor": "#dddddd"
      },
      "isElementDeleted": false
    }
  }
}
```

### Additional Considerations

Consider the following when working with the Comments Schema in the Beefree SDK:

* **Dynamic Commenting**: Attaching comments at runtime requires accurate mapping of `elementId` values—typically handled by advanced API interactions.
* **Draft vs. Final**: Host apps may choose to persist comments only for drafts or historical versions of templates.
* **Performance**: For templates with large comment trees, consider lazy-loading responses to optimize rendering.


---

# 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.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.