From ce646c87ddcb20fa6b0298ce22dfd30f5d285969 Mon Sep 17 00:00:00 2001
From: Trang Doan <doantranghp2000@gmail.com>
Date: Tue, 30 Jun 2026 18:26:14 -0400
Subject: [PATCH] ENG-1975 Add schema file contract and shared foundation for
 Obsidian export/import.
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds DiscourseSchemaFile and DiscourseSchemaTemplate type definitions, plus
getDgSchemaFileName and DG_SCHEMA_EXPORT_VERSION — the minimal shared primitives
needed by both the schema export (ENG-1976) and import (ENG-1977) features.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 apps/obsidian/src/types.ts                | 16 +++++
 apps/obsidian/src/utils/specValidation.ts | 83 +++++++++++++++++++++++
 2 files changed, 99 insertions(+)
 create mode 100644 apps/obsidian/src/utils/specValidation.ts

diff --git a/apps/obsidian/src/types.ts b/apps/obsidian/src/types.ts
index f7bc3fc41..a43ba9ae3 100644
--- a/apps/obsidian/src/types.ts
+++ b/apps/obsidian/src/types.ts
@@ -117,4 +117,20 @@ export type ImportFolderMetadata = {
   userName?: string;
 };
 
+export type DiscourseSchemaTemplate = {
+  name: string;
+  content: string;
+};
+
+export type DiscourseSchemaFile = {
+  version: number;
+  exportedAt: string;
+  pluginVersion: string;
+  vaultName: string;
+  nodeTypes: DiscourseNode[];
+  relationTypes: DiscourseRelationType[];
+  discourseRelations: DiscourseRelation[];
+  templates: DiscourseSchemaTemplate[];
+};
+
 export const VIEW_TYPE_DISCOURSE_CONTEXT = "discourse-context-view";
diff --git a/apps/obsidian/src/utils/specValidation.ts b/apps/obsidian/src/utils/specValidation.ts
new file mode 100644
index 000000000..b9662e548
--- /dev/null
+++ b/apps/obsidian/src/utils/specValidation.ts
@@ -0,0 +1,83 @@
+import { z } from "zod";
+import type { DiscourseSchemaFile } from "~/types";
+
+export const DG_SCHEMA_EXPORT_VERSION = 1;
+
+const discourseNodeSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  format: z.string(),
+  template: z.string().optional(),
+  description: z.string().optional(),
+  shortcut: z.string().optional(),
+  color: z.string().optional(),
+  tag: z.string().optional(),
+  keyImage: z.boolean().optional(),
+  folderPath: z.string().optional(),
+  created: z.number(),
+  modified: z.number(),
+  importedFromRid: z.string().optional(),
+  authorId: z.number().optional(),
+});
+
+const relationImportStatusSchema = z.enum(["provisional", "accepted"]);
+
+const discourseRelationTypeSchema = z.object({
+  id: z.string(),
+  label: z.string(),
+  complement: z.string(),
+  color: z.string(),
+  created: z.number(),
+  modified: z.number(),
+  importedFromRid: z.string().optional(),
+  status: relationImportStatusSchema.optional(),
+  authorId: z.number().optional(),
+});
+
+const discourseRelationSchema = z.object({
+  id: z.string(),
+  sourceId: z.string(),
+  destinationId: z.string(),
+  relationshipTypeId: z.string(),
+  created: z.number(),
+  modified: z.number(),
+  importedFromRid: z.string().optional(),
+  status: relationImportStatusSchema.optional(),
+  authorId: z.number().optional(),
+});
+
+const templateExportSchema = z.object({
+  name: z.string(),
+  content: z.string(),
+});
+
+export const dgSchemaFileSchema = z.object({
+  version: z.literal(DG_SCHEMA_EXPORT_VERSION),
+  exportedAt: z.string(),
+  pluginVersion: z.string(),
+  vaultName: z.string(),
+  nodeTypes: z.array(discourseNodeSchema),
+  relationTypes: z.array(discourseRelationTypeSchema),
+  discourseRelations: z.array(discourseRelationSchema),
+  templates: z.array(templateExportSchema),
+});
+
+const normalizeToKebabCase = (value: string): string => {
+  return value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .replace(/-{2,}/g, "-");
+};
+
+export const getDgSchemaFileName = (vaultName?: string): string => {
+  const normalizedVaultName = vaultName ? normalizeToKebabCase(vaultName) : "";
+  const safeVaultName =
+    normalizedVaultName.length > 0 ? normalizedVaultName : "vault";
+  return `dg-schema-${safeVaultName}.json`;
+};
+
+export const parseDgSchemaFile = (value: unknown): DiscourseSchemaFile => {
+  return dgSchemaFileSchema.parse(value) as DiscourseSchemaFile;
+};