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)

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

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