[WEB-5845] chore: changing description field to description json (#8230)

* chore: migrating description to description json

* chore: replace description with description_json

* chore: updated migration file

* chore: updated the migration file

* chore: added description key in external endpoint

* chore: updated the migration file

* chore: updated the typo

---------

Co-authored-by: Aaryan Khandelwal <aaryankhandu123@gmail.com>

apps/api/plane/api/serializers/intake.py

@@ -13,11 +13,14 @@ class IssueForIntakeSerializer(BaseSerializer):
     content validation and priority assignment for triage workflows.
     """
 
+    description = serializers.JSONField(source="description_json", required=False, allow_null=True)
+
     class Meta:
         model = Issue
         fields = [
             "name",
-            "description",
+            "description",  # Deprecated
+            "description_json",
             "description_html",
             "priority",
         ]

apps/api/plane/api/serializers/issue.py

@@ -65,7 +65,7 @@ class IssueSerializer(BaseSerializer):
     class Meta:
         model = Issue
         read_only_fields = ["id", "workspace", "project", "updated_by", "updated_at"]
-        exclude = ["description", "description_stripped"]
+        exclude = ["description_json", "description_stripped"]
 
     def validate(self, data):
         if (
@@ -633,6 +633,7 @@ class IssueExpandSerializer(BaseSerializer):
     labels = serializers.SerializerMethodField()
     assignees = serializers.SerializerMethodField()
     state = StateLiteSerializer(read_only=True)
+    description = serializers.JSONField(source="description_json", read_only=True)
 
     def get_labels(self, obj):
         expand = self.context.get("expand", [])

apps/api/plane/api/views/intake.py

@@ -180,11 +180,14 @@ class IntakeIssueListCreateAPIEndpoint(BaseAPIView):
             )
 
         # create an issue
+        issue_data = request.data.get("issue", {})
+        # Accept both "description" and "description_json" keys for the description_json field
+        description_json = issue_data.get("description") or issue_data.get("description_json") or {}
         issue = Issue.objects.create(
-            name=request.data.get("issue", {}).get("name"),
+            name=issue_data.get("name"),
-            description=request.data.get("issue", {}).get("description", {}),
+            description_json=description_json,
-            description_html=request.data.get("issue", {}).get("description_html", "<p></p>"),
+            description_html=issue_data.get("description_html", "<p></p>"),
-            priority=request.data.get("issue", {}).get("priority", "none"),
+            priority=issue_data.get("priority", "none"),
             project_id=project_id,
             state_id=triage_state.id,
         )
@@ -365,10 +368,11 @@ class IntakeIssueDetailAPIEndpoint(BaseAPIView):
 
             # Only allow guests to edit name and description
             if project_member.role <= 5:
+                description_json = issue_data.get("description") or issue_data.get("description_json") or {}
                 issue_data = {
                     "name": issue_data.get("name", issue.name),
                     "description_html": issue_data.get("description_html", issue.description_html),
-                    "description": issue_data.get("description", issue.description),
+                    "description_json": description_json,
                 }
 
             issue_serializer = IssueSerializer(issue, data=issue_data, partial=True)

apps/api/plane/app/serializers/issue.py

@@ -53,7 +53,7 @@ class IssueFlatSerializer(BaseSerializer):
         fields = [
             "id",
             "name",
-            "description",
+            "description_json",
             "description_html",
             "priority",
             "start_date",

apps/api/plane/app/serializers/page.py

@@ -58,7 +58,7 @@ class PageSerializer(BaseSerializer):
         labels = validated_data.pop("labels", None)
         project_id = self.context["project_id"]
         owned_by_id = self.context["owned_by_id"]
-        description = self.context["description"]
+        description_json = self.context["description_json"]
         description_binary = self.context["description_binary"]
         description_html = self.context["description_html"]
 
@@ -68,7 +68,7 @@ class PageSerializer(BaseSerializer):
         # Create the page
         page = Page.objects.create(
             **validated_data,
-            description=description,
+            description_json=description_json,
             description_binary=description_binary,
             description_html=description_html,
             owned_by_id=owned_by_id,
@@ -171,7 +171,7 @@ class PageBinaryUpdateSerializer(serializers.Serializer):
 
     description_binary = serializers.CharField(required=False, allow_blank=True)
     description_html = serializers.CharField(required=False, allow_blank=True)
-    description = serializers.JSONField(required=False, allow_null=True)
+    description_json = serializers.JSONField(required=False, allow_null=True)
 
     def validate_description_binary(self, value):
         """Validate the base64-encoded binary data"""
@@ -214,8 +214,8 @@ class PageBinaryUpdateSerializer(serializers.Serializer):
         if "description_html" in validated_data:
             instance.description_html = validated_data.get("description_html")
 
-        if "description" in validated_data:
+        if "description_json" in validated_data:
-            instance.description = validated_data.get("description")
+            instance.description_json = validated_data.get("description_json")
 
         instance.save()
         return instance

apps/api/plane/app/views/intake/base.py

@@ -394,7 +394,7 @@ class IntakeIssueViewSet(BaseViewSet):
                 issue_data = {
                     "name": issue_data.get("name", issue.name),
                     "description_html": issue_data.get("description_html", issue.description_html),
-                    "description": issue_data.get("description", issue.description),
+                    "description_json": issue_data.get("description_json", issue.description_json),
                 }
 
             issue_current_instance = json.dumps(IssueDetailSerializer(issue).data, cls=DjangoJSONEncoder)

apps/api/plane/app/views/page/base.py

@@ -128,7 +128,7 @@ class PageViewSet(BaseViewSet):
             context={
                 "project_id": project_id,
                 "owned_by_id": request.user.id,
-                "description": request.data.get("description", {}),
+                "description_json": request.data.get("description_json", {}),
                 "description_binary": request.data.get("description_binary", None),
                 "description_html": request.data.get("description_html", "<p></p>"),
             },

apps/api/plane/bgtasks/copy_s3_object.py

@@ -141,7 +141,7 @@ def copy_s3_objects_of_description_and_assets(entity_name, entity_identifier, pr
         external_data = sync_with_external_service(entity_name, updated_html)
 
         if external_data:
-            entity.description = external_data.get("description")
+            entity.description_json = external_data.get("description_json")
             entity.description_binary = base64.b64decode(external_data.get("description_binary"))
             entity.save()
 

apps/api/plane/bgtasks/issue_description_version_sync.py

@@ -59,7 +59,7 @@ def sync_issue_description_version(batch_size=5000, offset=0, countdown=300):
                     "description_binary",
                     "description_html",
                     "description_stripped",
-                    "description",
+                    "description_json",
                 )[offset:end_offset]
             )
 
@@ -92,7 +92,7 @@ def sync_issue_description_version(batch_size=5000, offset=0, countdown=300):
                         description_binary=issue.description_binary,
                         description_html=issue.description_html,
                         description_stripped=issue.description_stripped,
-                        description_json=issue.description,
+                        description_json=issue.description_json,
                     )
                 )
 

apps/api/plane/bgtasks/issue_description_version_task.py

@@ -19,7 +19,7 @@ def should_update_existing_version(
 
 
 def update_existing_version(version: IssueDescriptionVersion, issue) -> None:
-    version.description_json = issue.description
+    version.description_json = issue.description_json
     version.description_html = issue.description_html
     version.description_binary = issue.description_binary
     version.description_stripped = issue.description_stripped

apps/api/plane/bgtasks/page_version_task.py

@@ -28,7 +28,7 @@ def page_version(page_id, existing_instance, user_id):
                 description_binary=page.description_binary,
                 owned_by_id=user_id,
                 last_saved_at=page.updated_at,
-                description_json=page.description,
+                description_json=page.description_json,
                 description_stripped=page.description_stripped,
             )
 

apps/api/plane/bgtasks/workspace_seed_task.py

@@ -359,7 +359,7 @@ def create_pages(workspace: Workspace, project_map: Dict[int, uuid.UUID], bot_us
             is_global=False,
             access=page_seed.get("access", Page.PUBLIC_ACCESS),
             name=page_seed.get("name"),
-            description=page_seed.get("description", {}),
+            description_json=page_seed.get("description_json", {}),
             description_html=page_seed.get("description_html", "<p></p>"),
             description_binary=page_seed.get("description_binary", None),
             description_stripped=page_seed.get("description_stripped", None),

apps/api/plane/db/migrations/0117_rename_description_draftissue_description_json_and_more.py

@@ -0,0 +1,28 @@
+# Generated by Django 4.2.22 on 2026-01-15 09:02
+
+from django.db import migrations
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('db', '0116_workspacemember_explored_features_and_more'),
+    ]
+
+    operations = [
+        migrations.RenameField(
+            model_name='draftissue',
+            old_name='description',
+            new_name='description_json',
+        ),
+        migrations.RenameField(
+            model_name='issue',
+            old_name='description',
+            new_name='description_json',
+        ),
+        migrations.RenameField(
+            model_name='page',
+            old_name='description',
+            new_name='description_json',
+        ),
+    ]

apps/api/plane/db/models/draft.py

@@ -39,7 +39,7 @@ class DraftIssue(WorkspaceBaseModel):
         blank=True,
     )
     name = models.CharField(max_length=255, verbose_name="Issue Name", blank=True, null=True)
-    description = models.JSONField(blank=True, default=dict)
+    description_json = models.JSONField(blank=True, default=dict)
     description_html = models.TextField(blank=True, default="<p></p>")
     description_stripped = models.TextField(blank=True, null=True)
     description_binary = models.BinaryField(null=True)

apps/api/plane/db/models/issue.py

@@ -128,7 +128,7 @@ class Issue(ProjectBaseModel):
         blank=True,
     )
     name = models.CharField(max_length=255, verbose_name="Issue Name")
-    description = models.JSONField(blank=True, default=dict)
+    description_json = models.JSONField(blank=True, default=dict)
     description_html = models.TextField(blank=True, default="<p></p>")
     description_stripped = models.TextField(blank=True, null=True)
     description_binary = models.BinaryField(null=True)
@@ -800,7 +800,7 @@ class IssueDescriptionVersion(ProjectBaseModel):
                 description_binary=issue.description_binary,
                 description_html=issue.description_html,
                 description_stripped=issue.description_stripped,
-                description_json=issue.description,
+                description_json=issue.description_json,
             )
             return True
         except Exception as e:

apps/api/plane/db/models/page.py

@@ -25,7 +25,7 @@ class Page(BaseModel):
 
     workspace = models.ForeignKey("db.Workspace", on_delete=models.CASCADE, related_name="pages")
     name = models.TextField(blank=True)
-    description = models.JSONField(default=dict, blank=True)
+    description_json = models.JSONField(default=dict, blank=True)
     description_binary = models.BinaryField(null=True)
     description_html = models.TextField(blank=True, default="<p></p>")
     description_stripped = models.TextField(blank=True, null=True)

apps/api/plane/space/serializer/issue.py

@@ -193,7 +193,7 @@ class IssueFlatSerializer(BaseSerializer):
         fields = [
             "id",
             "name",
-            "description",
+            "description_json",
             "description_html",
             "priority",
             "start_date",

apps/api/plane/space/views/intake.py

@@ -140,7 +140,7 @@ class IntakeIssuePublicViewSet(BaseViewSet):
         # create an issue
         issue = Issue.objects.create(
             name=request.data.get("issue", {}).get("name"),
-            description=request.data.get("issue", {}).get("description", {}),
+            description_json=request.data.get("issue", {}).get("description_json", {}),
             description_html=request.data.get("issue", {}).get("description_html", "<p></p>"),
             priority=request.data.get("issue", {}).get("priority", "low"),
             project_id=project_deploy_board.project_id,
@@ -201,7 +201,7 @@ class IntakeIssuePublicViewSet(BaseViewSet):
         issue_data = {
             "name": issue_data.get("name", issue.name),
             "description_html": issue_data.get("description_html", issue.description_html),
-            "description": issue_data.get("description", issue.description),
+            "description_json": issue_data.get("description_json", issue.description_json),
         }
 
         issue_serializer = IssueCreateSerializer(

apps/api/plane/space/views/issue.py

@@ -744,7 +744,7 @@ class IssueRetrievePublicEndpoint(BaseAPIView):
                 "name",
                 "state_id",
                 "sort_order",
-                "description",
+                "description_json",
                 "description_html",
                 "description_stripped",
                 "description_binary",

apps/live/src/controllers/document.controller.ts

@@ -27,14 +27,14 @@ export class DocumentController {
       const { description_html, variant } = validatedData;
 
       // Process document conversion
-      const { description, description_binary } = convertHTMLDocumentToAllFormats({
+      const { description_json, description_binary } = convertHTMLDocumentToAllFormats({
         document_html: description_html,
         variant,
       });
 
       // Return successful response
       res.status(200).json({
-        description,
+        description_json,
         description_binary,
       });
     } catch (error) {

apps/live/src/extensions/database.ts

@@ -1,11 +1,12 @@
 import { Database as HocuspocusDatabase } from "@hocuspocus/extension-database";
-// utils
+// plane imports
 import {
   getAllDocumentFormatsFromDocumentEditorBinaryData,
   getBinaryDataFromDocumentEditorHTMLString,
 } from "@plane/editor";
-// logger
+import type { TDocumentPayload } from "@plane/types";
 import { logger } from "@plane/logger";
+// lib
 import { AppError } from "@/lib/errors";
 // services
 import { getPageService } from "@/services/page/handler";
@@ -36,10 +37,10 @@ const fetchDocument = async ({ context, documentName: pageId, instance }: FetchP
             convertedBinaryData,
             true
           );
-          const payload = {
+          const payload: TDocumentPayload = {
             description_binary: contentBinaryEncoded,
             description_html: contentHTML,
-            description: contentJSON,
+            description_json: contentJSON,
           };
           await service.updateDescriptionBinary(pageId, payload);
         } catch (e) {
@@ -76,10 +77,10 @@ const storeDocument = async ({
       true
     );
     // create payload
-    const payload = {
+    const payload: TDocumentPayload = {
       description_binary: contentBinaryEncoded,
       description_html: contentHTML,
-      description: contentJSON,
+      description_json: contentJSON,
     };
     await service.updateDescriptionBinary(pageId, payload);
   } catch (error) {

apps/live/src/services/page/core.service.ts

@@ -1,15 +1,9 @@
 import { logger } from "@plane/logger";
-import type { TPage } from "@plane/types";
+import type { TDocumentPayload, TPage } from "@plane/types";
 // services
 import { AppError } from "@/lib/errors";
 import { APIService } from "../api.service";
 
-export type TPageDescriptionPayload = {
-  description_binary: string;
-  description_html: string;
-  description: object;
-};
-
 export abstract class PageCoreService extends APIService {
   protected abstract basePath: string;
 
@@ -103,7 +97,7 @@ export abstract class PageCoreService extends APIService {
     }
   }
 
-  async updateDescriptionBinary(pageId: string, data: TPageDescriptionPayload): Promise<any> {
+  async updateDescriptionBinary(pageId: string, data: TDocumentPayload): Promise<any> {
     return this.patch(`${this.basePath}/pages/${pageId}/description/`, data, {
       headers: this.getHeader(),
     })

apps/web/core/hooks/use-page-fallback.ts

@@ -59,7 +59,7 @@ export const usePageFallback = (args: TArgs) => {
       await updatePageDescription({
         description_binary: encodedBinary,
         description_html: html,
-        description: json,
+        description_json: json,
       });
     } catch (error: any) {
       console.error(error);

apps/web/core/store/pages/base-page.ts

@@ -80,7 +80,7 @@ export class BasePage extends ExtendedBasePage implements TBasePage {
   id: string | undefined;
   name: string | undefined;
   logo_props: TLogoProps | undefined;
-  description: object | undefined;
+  description_json: object | undefined;
   description_html: string | undefined;
   color: string | undefined;
   label_ids: string[] | undefined;
@@ -117,7 +117,7 @@ export class BasePage extends ExtendedBasePage implements TBasePage {
     this.id = page?.id || undefined;
     this.name = page?.name;
     this.logo_props = page?.logo_props || undefined;
-    this.description = page?.description || undefined;
+    this.description_json = page?.description_json || undefined;
     this.description_html = page?.description_html || undefined;
     this.color = page?.color || undefined;
     this.label_ids = page?.label_ids || undefined;
@@ -142,7 +142,7 @@ export class BasePage extends ExtendedBasePage implements TBasePage {
       id: observable.ref,
       name: observable.ref,
       logo_props: observable.ref,
-      description: observable,
+      description_json: observable.ref,
       description_html: observable.ref,
       color: observable.ref,
       label_ids: observable,
@@ -217,7 +217,7 @@ export class BasePage extends ExtendedBasePage implements TBasePage {
     return {
       id: this.id,
       name: this.name,
-      description: this.description,
+      description_json: this.description_json,
       description_html: this.description_html,
       color: this.color,
       label_ids: this.label_ids,

packages/editor/src/core/helpers/yjs-utils.ts

@@ -215,7 +215,7 @@ export const convertHTMLDocumentToAllFormats = (args: TConvertHTMLDocumentToAllF
     const { contentBinaryEncoded, contentHTML, contentJSON } =
       getAllDocumentFormatsFromRichTextEditorBinaryData(contentBinary);
     allFormats = {
-      description: contentJSON,
+      description_json: contentJSON,
       description_html: contentHTML,
       description_binary: contentBinaryEncoded,
     };
@@ -228,7 +228,7 @@ export const convertHTMLDocumentToAllFormats = (args: TConvertHTMLDocumentToAllF
       false
     );
     allFormats = {
-      description: contentJSON,
+      description_json: contentJSON,
       description_html: contentHTML,
       description_binary: contentBinaryEncoded,
     };

packages/types/src/page/core.ts

@@ -8,7 +8,7 @@ export type TPage = {
   color: string | undefined;
   created_at: Date | undefined;
   created_by: string | undefined;
-  description: object | undefined;
+  description_json: object | undefined;
   description_html: string | undefined;
   id: string | undefined;
   is_favorite: boolean;
@@ -66,7 +66,7 @@ export type TPageVersion = {
 export type TDocumentPayload = {
   description_binary: string;
   description_html: string;
-  description: object;
+  description_json: object;
 };
 
 export type TWebhookConnectionQueryParams = {