feat(dashboards): report dashboard parse errors on file writes

The v2 file create, replace and edit responses now carry `diagnostics` for a
dashboard file: its parse errors, or an empty list. Writes are never blocked,
like the page lint; table columns and queries are still checked when panels
render. Parse errors are reported as `path: message` lines, and a block with
no recognized kind names the allowed kinds and unknown keys instead of Zod's
union dump.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01S6aTRnkiu7PxYZPNPXYEMV

Author: TheodoreSpeaks

apps/docs/openapi-v2-files-audit.json

@@ -248,7 +248,7 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/V2FileResponse"
+                  "$ref": "#/components/schemas/V2CreatedFileResponse"
                 }
               }
             }
@@ -4044,18 +4044,115 @@
           }
         ]
       },
-      "V2FileResponse": {
+      "V2CreatedFile": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Unique file identifier.",
+            "examples": ["wf_V1StGXR8z5jdHi6BmyT91"]
+          },
+          "webUrl": {
+            "type": "string",
+            "format": "uri",
+            "description": "Canonical absolute URL for opening this resource in the Sim web application."
+          },
+          "name": {
+            "type": "string",
+            "description": "Original file name.",
+            "examples": ["data.csv"]
+          },
+          "size": {
+            "type": "number",
+            "minimum": 0,
+            "description": "Size in bytes of the stored file. For a generated document (docx, pptx, pdf, xlsx) this is the generation source, not the rendered document, so it does not predict how many bytes downloading the file returns.",
+            "examples": [1024]
+          },
+          "type": {
+            "type": "string",
+            "description": "MIME type of the stored file. For a generated document (docx, pptx, pdf, xlsx) this is the generation source type, not the rendered document type a download serves.",
+            "examples": ["text/csv"]
+          },
+          "key": {
+            "type": "string",
+            "description": "Storage key for the file.",
+            "examples": ["workspace/example/data.csv"]
+          },
+          "folderPath": {
+            "type": "string",
+            "title": "Folder path",
+            "description": "Canonical containing-folder path. `/` is the workspace root.",
+            "maxLength": 4096
+          },
+          "uploadedByEmail": {
+            "type": "string",
+            "format": "email",
+            "pattern": "^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$",
+            "description": "Current email address of the uploader.",
+            "examples": ["jane@example.com"]
+          },
+          "uploadedAt": {
+            "type": "string",
+            "description": "ISO 8601 timestamp when the file was uploaded.",
+            "format": "date-time",
+            "examples": ["2026-01-15T10:30:00Z"]
+          },
+          "updatedAt": {
+            "type": "string",
+            "description": "ISO 8601 timestamp of the last content or metadata write.",
+            "format": "date-time",
+            "examples": ["2026-01-15T10:30:00Z"]
+          },
+          "deletedAt": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "ISO 8601 timestamp when the file was archived by deleting it, or null while the file is active. Only an archived-scope file list returns files with a non-null value.",
+            "format": "date-time",
+            "examples": ["2026-01-16T09:00:00Z"]
+          },
+          "diagnostics": {
+            "description": "For a dashboard file, the YAML parse errors in the written content. Empty when it parses; the file is saved either way. Absent for other file types.",
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        },
+        "required": [
+          "id",
+          "webUrl",
+          "name",
+          "size",
+          "type",
+          "key",
+          "folderPath",
+          "uploadedByEmail",
+          "uploadedAt",
+          "updatedAt",
+          "deletedAt"
+        ],
+        "additionalProperties": false,
+        "title": "Created file",
+        "description": "A newly created workspace file, with any dashboard parse errors."
+      },
+      "V2CreatedFileResponse": {
         "type": "object",
         "properties": {
           "data": {
             "description": "Response data.",
-            "$ref": "#/components/schemas/V2File"
+            "$ref": "#/components/schemas/V2CreatedFile"
           }
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "File response",
-        "description": "A single workspace file.",
+        "title": "Created file response",
+        "description": "A newly created workspace file, with any dashboard parse errors.",
         "examples": [
           {
             "data": {
@@ -5115,6 +5212,36 @@
         "title": "Delete file response",
         "description": "Deletion confirmation for one file."
       },
+      "V2FileResponse": {
+        "type": "object",
+        "properties": {
+          "data": {
+            "description": "Response data.",
+            "$ref": "#/components/schemas/V2File"
+          }
+        },
+        "required": ["data"],
+        "additionalProperties": false,
+        "title": "File response",
+        "description": "A single workspace file.",
+        "examples": [
+          {
+            "data": {
+              "id": "wf_V1StGXR8z5jdHi6BmyT91",
+              "webUrl": "https://www.sim.ai/workspace/a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64/files/wf_V1StGXR8z5jdHi6BmyT91",
+              "name": "data.csv",
+              "size": 1024,
+              "type": "text/csv",
+              "key": "workspace/example/data.csv",
+              "folderPath": "/Engineering",
+              "uploadedByEmail": "jane@example.com",
+              "uploadedAt": "2026-01-15T10:30:00Z",
+              "updatedAt": "2026-01-15T10:30:00Z",
+              "deletedAt": null
+            }
+          }
+        ]
+      },
       "RenameFileRequest": {
         "type": "object",
         "properties": {
@@ -5832,6 +5959,13 @@
           "revision": {
             "description": "Opaque token for the content this write produced. Send it back as `expectedRevision` on the next write. Absent for a file with no recorded content version.",
             "type": "string"
+          },
+          "diagnostics": {
+            "description": "For a dashboard file, the YAML parse errors in the written content. Empty when it parses; the file is saved either way. Absent for other file types.",
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
           }
         },
         "required": ["file", "lineCount"],
@@ -6234,6 +6368,13 @@
           "revision": {
             "description": "Opaque token for the content this write produced. Send it back as `expectedRevision` on the next write. Absent for a file with no recorded content version.",
             "type": "string"
+          },
+          "diagnostics": {
+            "description": "For a dashboard file, the YAML parse errors in the written content. Empty when it parses; the file is saved either way. Absent for other file types.",
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
           }
         },
         "required": [

apps/sim/app/api/v2/files/[fileId]/content/route.ts

@@ -40,8 +40,12 @@ export const PUT = defineV2JsonRoute({
     expectedRevision: body.expectedRevision,
   }),
   useCase: updateWorkspaceFileContent,
-  present: async ({ file }) => ({
-    data: { ...(await toV2File(file)), ...workspaceFileRevisionField(file) },
+  present: async ({ file, diagnostics }) => ({
+    data: {
+      ...(await toV2File(file)),
+      ...workspaceFileRevisionField(file),
+      ...(diagnostics ? { diagnostics } : {}),
+    },
   }),
 })
 
@@ -77,7 +81,12 @@ export const PATCH = defineV2JsonRoute({
     expectedRevision: body.expectedRevision,
   }),
   useCase: editWorkspaceFileContent,
-  present: async ({ file, lineCount }) => ({
-    data: { file: await toV2File(file), lineCount, ...workspaceFileRevisionField(file) },
+  present: async ({ file, lineCount, diagnostics }) => ({
+    data: {
+      file: await toV2File(file),
+      lineCount,
+      ...workspaceFileRevisionField(file),
+      ...(diagnostics ? { diagnostics } : {}),
+    },
   }),
 })

apps/sim/app/api/v2/files/route.ts

@@ -93,5 +93,7 @@ export const POST = defineV2JsonRoute({
     exactName: true,
   }),
   useCase: createWorkspaceFile,
-  present: async ({ file }) => ({ data: await toV2File(file) }),
+  present: async ({ file, diagnostics }) => ({
+    data: { ...(await toV2File(file)), ...(diagnostics ? { diagnostics } : {}) },
+  }),
 })

apps/sim/lib/api/contracts/v2/files.ts

@@ -758,14 +758,30 @@ export const v2ListFilesContract = defineRouteContract({
   },
 })
 
+/** Dashboard parse errors for the written content; only present for dashboard files. */
+const fileDiagnosticsSchema = z
+  .array(z.string())
+  .optional()
+  .describe(
+    'For a dashboard file, the YAML parse errors in the written content. Empty when it parses; the file is saved either way. Absent for other file types.'
+  )
+
+export const v2CreatedFileSchema = v2FileSchema
+  .extend({ diagnostics: fileDiagnosticsSchema })
+  .meta({
+    id: 'V2CreatedFile',
+    title: 'Created file',
+    description: 'A newly created workspace file, with any dashboard parse errors.',
+  })
+
 export const v2CreateFileContract = defineRouteContract({
   method: 'POST',
   path: '/api/v2/files',
   query: noInputSchema,
   body: v2CreateFileBodySchema,
   response: {
     mode: 'json',
-    schema: v2DataResponse(v2FileSchema),
+    schema: v2DataResponse(v2CreatedFileSchema),
     status: 201,
   },
 })
@@ -1265,6 +1281,7 @@ export const v2EditedFileSchema = z
     file: v2FileSchema.describe('The file after the edit.'),
     lineCount: z.number().int().nonnegative().describe('Lines the file holds after the edit.'),
     revision: writtenFileRevisionSchema,
+    diagnostics: fileDiagnosticsSchema,
   })
   .strict()
   .meta({
@@ -1496,7 +1513,7 @@ export const v2EditFileContentContract = defineRouteContract({
 })
 
 export const v2WrittenFileSchema = v2FileSchema
-  .extend({ revision: writtenFileRevisionSchema })
+  .extend({ revision: writtenFileRevisionSchema, diagnostics: fileDiagnosticsSchema })
   .meta({
     id: 'V2WrittenFile',
     title: 'Written file',

apps/sim/lib/api/contracts/v2/openapi/files-audit.ts

@@ -208,9 +208,9 @@ const declaredRoutes = [
       ),
       response: documentedSchema(
         v2CreateFileContract.response.schema,
-        'V2FileResponse',
-        'File response',
-        'A single workspace file.',
+        'V2CreatedFileResponse',
+        'Created file response',
+        'A newly created workspace file, with any dashboard parse errors.',
         [{ data: FILE_EXAMPLE }]
       ),
     }

apps/sim/lib/dashboards/README.md

@@ -4,7 +4,7 @@ A dashboard is a workspace file with MIME type `text/x-sim-dashboard`, handled l
 
 The implementation has three boundaries:
 
-- `spec.ts` validates a bounded YAML document and normalizes ECharts options through the existing `.chart` safety rules. It rejects unknown layout/source keys and reports errors in the viewer. Nothing validates the file on write.
+- `spec.ts` validates a bounded YAML document and normalizes ECharts options through the existing `.chart` safety rules. It rejects unknown layout/source keys and reports errors in the viewer. Writes are never blocked: the v2 file create, replace and edit responses carry `diagnostics` for a dashboard file (parse errors as `path: message` lines, or an empty list), like the page lint. Table columns and queries are only checked when panels render.
 - `table/analytics` computes exact aggregates over authorized table rows. The internal POST `/api/table/[tableId]/analytics` is a session-authenticated adapter for `tables.rows.analytics`, requiring the current viewer's workspace read role and `tables.use`. The operation is session-only because this release's sole query caller is the workspace renderer. Public/versioned query APIs, workflow/executor callers and log queries are deferred.
 - `components/dashboards` owns EMCN layout, controls and states. `components/charts/echarts-view.tsx` also renders existing `.chart` files, using the local EMCN tokens for its canvas theme. `.chart` retains its existing sampled source behavior; dashboard aggregation is performed on the server.
 

apps/sim/lib/dashboards/diagnostics.ts

@@ -0,0 +1,16 @@
+import { DASHBOARD_CONTENT_TYPE } from '@/lib/dashboards/file'
+import { parseDashboardSpec } from '@/lib/dashboards/spec'
+
+/**
+ * Parse errors for a dashboard file's content, reported on write without blocking it, like
+ * the page lint. Undefined for other file types; an empty list means the YAML parsed. Table
+ * columns and queries are only checked when the dashboard renders.
+ */
+export function dashboardDiagnostics(
+  contentType: string,
+  content: Buffer | string
+): string[] | undefined {
+  if (contentType !== DASHBOARD_CONTENT_TYPE) return undefined
+  const { error } = parseDashboardSpec(content.toString())
+  return error ? [error] : []
+}

apps/sim/lib/dashboards/spec.test.ts

@@ -110,3 +110,25 @@ describe('UTC ranges', () => {
     expect(() => parseDashboardCustomRange(from, to)).toThrow()
   )
 })
+
+describe('dashboard parse errors', () => {
+  it('names the block path, the allowed block kinds and any unknown key', () => {
+    expect(parseDashboardSpec('title: Probe\nblocks:\n  - bogus: 1\n').error).toBe(
+      'blocks.0: expected a block with one of text, stat, chart, table, row, tabs; unknown key "bogus"'
+    )
+  })
+
+  it('does not describe a measure union as a block', () => {
+    const error = parseDashboardSpec(
+      'title: Probe\nsource: {tableId: tbl_1}\nblocks:\n  - stat: Total\n    source: {aggregate: {n: {op: nope}}}\n'
+    ).error
+    expect(error).toMatch(/^source\.aggregate\.n\.op: |^blocks\.0\.source\.aggregate\.n/)
+    expect(error).not.toContain('expected a block')
+  })
+
+  it('reports field errors at their path', () => {
+    expect(parseDashboardSpec('title: Probe\nblocks: []\n').error).toBe(
+      'blocks: Too small: expected array to have >=1 items'
+    )
+  })
+})