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)

{
  "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

{
  "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.