@opendata-ai/openchart-engine 8.0.0-rc.1 → 8.0.0-rc.10

package/src/compiler/validate.ts

@@ -16,6 +16,7 @@ import {
   MARK_TYPES,
   type MarkType,
   resolveSchemeName,
+  SEQUENTIAL_PALETTES,
   SUPPORTED_SCHEME_NAMES,
   type VizSpec,
 } from '@opendata-ai/openchart-core';
@@ -107,6 +108,94 @@ function didYouMean(field: string, columns: string[]): string {
   return match ? ` Did you mean "${match}"?` : '';
 }
 
+/**
+ * Push an INVALID_VALUE error when a channel carries an unrecognized
+ * scale.scheme name. Chart specs are the only family that consumes schemes
+ * this way: known names (including VL aliases) resolve via the core palette
+ * registry and are expanded to scale.range by the pre-validation sugar pass,
+ * so `resolveSchemeName` failing means the name is unknown.
+ */
+function checkSchemeName(
+  channelObj: Record<string, unknown>,
+  channelPath: string,
+  errors: ValidationError[],
+): void {
+  const scale = channelObj.scale as Record<string, unknown> | undefined;
+  if (scale && typeof scale.scheme === 'string' && !resolveSchemeName(scale.scheme)) {
+    errors.push({
+      message: `Spec error: ${channelPath}.scale.scheme "${scale.scheme}" is not a supported scheme name`,
+      path: `${channelPath}.scale.scheme`,
+      code: 'INVALID_VALUE',
+      suggestion: `Use one of the supported scheme names: ${[...SUPPORTED_SCHEME_NAMES].join(', ')}. Or provide explicit colors via scale.range.`,
+    });
+  }
+}
+
+/**
+ * Push an INVALID_VALUE error when any channel of an encoding block carries a
+ * scale.scheme on a spec family whose compile path never reads it. Even a
+ * known scheme name is dead config there — silently accepting it would leave
+ * the author believing they chose the colors.
+ */
+function checkSchemeUnused(
+  encoding: Record<string, unknown>,
+  errors: ValidationError[],
+  familyNote: string,
+  suggestion: string,
+): void {
+  for (const [channel, ch] of Object.entries(encoding)) {
+    if (!ch || typeof ch !== 'object' || Array.isArray(ch)) continue;
+    const scale = (ch as Record<string, unknown>).scale as Record<string, unknown> | undefined;
+    if (scale && typeof scale.scheme === 'string') {
+      errors.push({
+        message: `Spec error: encoding.${channel}.scale.scheme has no effect — ${familyNote}`,
+        path: `encoding.${channel}.scale.scheme`,
+        code: 'INVALID_VALUE',
+        suggestion,
+      });
+    }
+  }
+}
+
+/** Palette names the map compile path actually supports (sequential only). */
+const MAP_PALETTE_NAMES = Object.keys(SEQUENTIAL_PALETTES).join(', ');
+
+/**
+ * Map color channels resolve scale.scheme against SEQUENTIAL_PALETTES with a
+ * silent fallback to blue — a typo'd scheme would render the default palette
+ * with no signal. Reject names outside the map's supported set here instead.
+ * Categorical channels never read schemes at all (colors come from
+ * scale.domain/scale.range), so any scheme there is dead config.
+ */
+function checkMapSchemeName(
+  channelObj: Record<string, unknown>,
+  channelPath: string,
+  errors: ValidationError[],
+): void {
+  const scale = channelObj.scale as Record<string, unknown> | undefined;
+  if (!scale || typeof scale.scheme !== 'string') return;
+
+  if (channelObj.type === 'nominal' || channelObj.type === 'ordinal') {
+    errors.push({
+      message: `Spec error: ${channelPath}.scale.scheme has no effect — categorical map colors come from scale.range and scale.domain`,
+      path: `${channelPath}.scale.scheme`,
+      code: 'INVALID_VALUE',
+      suggestion:
+        'Remove scale.scheme. To customize categorical map colors, provide explicit colors via scale.range (with scale.domain for category order).',
+    });
+    return;
+  }
+
+  if (!(scale.scheme in SEQUENTIAL_PALETTES)) {
+    errors.push({
+      message: `Spec error: ${channelPath}.scale.scheme "${scale.scheme}" is not a supported map palette`,
+      path: `${channelPath}.scale.scheme`,
+      code: 'INVALID_VALUE',
+      suggestion: `Maps support the sequential palettes: ${MAP_PALETTE_NAMES}. The default is "blue".`,
+    });
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Range mark validation
 // ---------------------------------------------------------------------------
@@ -613,19 +702,7 @@ function validateChartSpec(spec: Record<string, unknown>, errors: ValidationErro
     // Check scale.scheme names. Known names (including VL aliases) are
     // resolved to palette ranges by the pre-validation sugar expansion, so a
     // scheme surviving to this point on the compile path is an unknown name.
-    const channelScale = channelObj.scale as Record<string, unknown> | undefined;
-    if (
-      channelScale &&
-      typeof channelScale.scheme === 'string' &&
-      !resolveSchemeName(channelScale.scheme)
-    ) {
-      errors.push({
-        message: `Spec error: encoding.${channel}.scale.scheme "${channelScale.scheme}" is not a supported scheme name`,
-        path: `encoding.${channel}.scale.scheme`,
-        code: 'INVALID_VALUE',
-        suggestion: `Use one of the supported scheme names: ${[...SUPPORTED_SCHEME_NAMES].join(', ')}. Or provide explicit colors via scale.range.`,
-      });
-    }
+    checkSchemeName(channelObj, `encoding.${channel}`, errors);
 
     // Check field type is allowed for this channel
     if (channelRule && channelObj.type && channelRule.allowedTypes.length > 0) {
@@ -763,6 +840,58 @@ function validateChartSpec(spec: Record<string, unknown>, errors: ValidationErro
     }
   }
 
+  // Validate row/column facet channels
+  for (const channel of ['row', 'column'] as const) {
+    const ch = (encoding as Record<string, unknown>)[channel];
+    if (ch && typeof ch === 'object') {
+      const facetCh = ch as Record<string, unknown>;
+      if (!facetCh.field || typeof facetCh.field !== 'string') {
+        errors.push({
+          message: `Spec error: encoding.${channel}.field is required and must be a non-empty string`,
+          path: `encoding.${channel}.field`,
+          code: 'MISSING_FIELD',
+          suggestion: `Add a field property to encoding.${channel} (e.g. { field: "category", type: "nominal" })`,
+        });
+      } else if (
+        !dataColumns.has(facetCh.field as string) &&
+        !transformFields.has(facetCh.field as string)
+      ) {
+        errors.push({
+          message: `Spec error: encoding.${channel}.field "${facetCh.field}" does not exist in data. Available columns: ${availableColumns}`,
+          path: `encoding.${channel}.field`,
+          code: 'DATA_FIELD_MISSING',
+          suggestion: `Use one of the available data columns: ${availableColumns}.${didYouMean(facetCh.field as string, columnList)}`,
+        });
+      }
+      if (!facetCh.type || (facetCh.type !== 'nominal' && facetCh.type !== 'ordinal')) {
+        errors.push({
+          message: `Spec error: encoding.${channel}.type must be "nominal" or "ordinal"${facetCh.type ? `, got "${facetCh.type}"` : ''}`,
+          path: `encoding.${channel}.type`,
+          code: facetCh.type ? 'INVALID_VALUE' : 'MISSING_FIELD',
+          suggestion: `Set encoding.${channel}.type to "nominal" or "ordinal"`,
+        });
+      }
+      if (encoding.facet && typeof encoding.facet === 'object') {
+        errors.push({
+          message: `Spec error: encoding.${channel} and encoding.facet cannot be used together`,
+          path: `encoding.${channel}`,
+          code: 'INVALID_VALUE',
+          suggestion: `Use either encoding.${channel} or encoding.facet, not both`,
+        });
+      }
+      const otherChannel = channel === 'row' ? 'column' : 'row';
+      if ((encoding as Record<string, unknown>)[otherChannel]) {
+        errors.push({
+          message:
+            'Spec error: encoding.row and encoding.column cannot be used together (cross-product faceting is not yet supported)',
+          path: `encoding.${channel}`,
+          code: 'INVALID_VALUE',
+          suggestion: 'Use encoding.facet with columns for grid layout, or use only row or column',
+        });
+      }
+    }
+  }
+
   // Validate darkMode if provided
   if (spec.darkMode !== undefined && !VALID_DARK_MODES.has(spec.darkMode as string)) {
     errors.push({
@@ -1022,7 +1151,7 @@ function validateGraphSpec(spec: Record<string, unknown>, errors: ValidationErro
         message: `Spec error: edges[${i}].source "${edge.source}" does not reference an existing node id`,
         path: `edges[${i}].source`,
         code: 'DATA_FIELD_MISSING',
-        suggestion: `Use one of the existing node ids: ${[...nodeIds].slice(0, 5).join(', ')}${nodeIds.size > 5 ? '...' : ''}`,
+        suggestion: `Use one of the existing node ids: ${[...nodeIds].slice(0, 5).join(', ')}${nodeIds.size > 5 ? '...' : ''}.${didYouMean(edge.source, [...nodeIds])}`,
       });
     }
 
@@ -1038,7 +1167,7 @@ function validateGraphSpec(spec: Record<string, unknown>, errors: ValidationErro
         message: `Spec error: edges[${i}].target "${edge.target}" does not reference an existing node id`,
         path: `edges[${i}].target`,
         code: 'DATA_FIELD_MISSING',
-        suggestion: `Use one of the existing node ids: ${[...nodeIds].slice(0, 5).join(', ')}${nodeIds.size > 5 ? '...' : ''}`,
+        suggestion: `Use one of the existing node ids: ${[...nodeIds].slice(0, 5).join(', ')}${nodeIds.size > 5 ? '...' : ''}.${didYouMean(edge.target, [...nodeIds])}`,
       });
     }
   }
@@ -1059,7 +1188,7 @@ function validateGraphSpec(spec: Record<string, unknown>, errors: ValidationErro
           message: `Spec error: encoding.${channel}.field "${ch.field}" does not exist on nodes. Available fields: ${[...nodeFields].join(', ')}`,
           path: `encoding.${channel}.field`,
           code: 'DATA_FIELD_MISSING',
-          suggestion: `Use one of the node fields: ${[...nodeFields].join(', ')}`,
+          suggestion: `Use one of the node fields: ${[...nodeFields].join(', ')}.${didYouMean(ch.field, [...nodeFields])}`,
         });
       }
     }
@@ -1072,10 +1201,18 @@ function validateGraphSpec(spec: Record<string, unknown>, errors: ValidationErro
           message: `Spec error: encoding.${channel}.field "${ch.field}" does not exist on edges. Available fields: ${[...edgeFields].join(', ')}`,
           path: `encoding.${channel}.field`,
           code: 'DATA_FIELD_MISSING',
-          suggestion: `Use one of the edge fields: ${[...edgeFields].join(', ')}`,
+          suggestion: `Use one of the edge fields: ${[...edgeFields].join(', ')}.${didYouMean(ch.field, [...edgeFields])}`,
         });
       }
     }
+
+    // Graph never reads scale.scheme: colors come from scale.range/scale.domain
+    checkSchemeUnused(
+      encoding,
+      errors,
+      'graph colors come from scale.range and scale.domain',
+      'Remove scale.scheme. To customize graph colors, provide explicit colors via scale.range.',
+    );
   }
 
   // Validate layout type if specified
@@ -1147,7 +1284,8 @@ function validateSankeySpec(spec: Record<string, unknown>, errors: ValidationErr
 
   const encoding = spec.encoding as Record<string, unknown>;
   const dataColumns = new Set(Object.keys(firstRow as Record<string, unknown>));
-  const availableColumns = [...dataColumns].join(', ');
+  const columnList = [...dataColumns];
+  const availableColumns = columnList.join(', ');
 
   // Required channels
   for (const channel of ['source', 'target', 'value'] as const) {
@@ -1157,7 +1295,7 @@ function validateSankeySpec(spec: Record<string, unknown>, errors: ValidationErr
         message: `Spec error: sankey encoding requires "${channel}" channel`,
         path: `encoding.${channel}`,
         code: 'MISSING_FIELD',
-        suggestion: `Add encoding.${channel} with a field from your data (${availableColumns}). Example: ${channel}: { field: "${[...dataColumns][0] ?? 'myField'}", type: "${channel === 'value' ? 'quantitative' : 'nominal'}" }`,
+        suggestion: `Add encoding.${channel} with a field from your data (${availableColumns}). Example: ${channel}: { field: "${columnList[0] ?? 'myField'}", type: "${channel === 'value' ? 'quantitative' : 'nominal'}" }`,
       });
       continue;
     }
@@ -1177,11 +1315,19 @@ function validateSankeySpec(spec: Record<string, unknown>, errors: ValidationErr
         message: `Spec error: encoding.${channel}.field "${ch.field}" does not exist in data. Available columns: ${availableColumns}`,
         path: `encoding.${channel}.field`,
         code: 'DATA_FIELD_MISSING',
-        suggestion: `Use one of the available data columns: ${availableColumns}`,
+        suggestion: `Use one of the available data columns: ${availableColumns}.${didYouMean(ch.field as string, columnList)}`,
       });
     }
   }
 
+  // Sankey never reads scale.scheme: node colors cycle theme.colors.categorical
+  checkSchemeUnused(
+    encoding,
+    errors,
+    'sankey node colors cycle the theme categorical palette',
+    'Remove scale.scheme. To customize sankey colors, set theme.colors.categorical.',
+  );
+
   // Validate darkMode if provided
   if (spec.darkMode !== undefined && !VALID_DARK_MODES.has(spec.darkMode as string)) {
     errors.push({
@@ -1260,7 +1406,8 @@ function validateTileMapSpec(spec: Record<string, unknown>, errors: ValidationEr
 
     const encoding = spec.encoding as Record<string, unknown>;
     const dataColumns = new Set(Object.keys(firstRow as Record<string, unknown>));
-    const availableColumns = [...dataColumns].join(', ');
+    const columnList = [...dataColumns];
+    const availableColumns = columnList.join(', ');
 
     // Required channels
     for (const channel of ['state', 'value'] as const) {
@@ -1270,7 +1417,7 @@ function validateTileMapSpec(spec: Record<string, unknown>, errors: ValidationEr
           message: `Spec error: tilemap encoding requires "${channel}" channel`,
           path: `encoding.${channel}`,
           code: 'MISSING_FIELD',
-          suggestion: `Add encoding.${channel} with a field from your data (${availableColumns}). Example: ${channel}: { field: "${[...dataColumns][0] ?? 'myField'}", type: "${channel === 'value' ? 'quantitative' : 'nominal'}" }`,
+          suggestion: `Add encoding.${channel} with a field from your data (${availableColumns}). Example: ${channel}: { field: "${columnList[0] ?? 'myField'}", type: "${channel === 'value' ? 'quantitative' : 'nominal'}" }`,
         });
         continue;
       }
@@ -1290,12 +1437,23 @@ function validateTileMapSpec(spec: Record<string, unknown>, errors: ValidationEr
           message: `Spec error: encoding.${channel}.field "${ch.field}" does not exist in data. Available columns: ${availableColumns}`,
           path: `encoding.${channel}.field`,
           code: 'DATA_FIELD_MISSING',
-          suggestion: `Use one of the available data columns: ${availableColumns}`,
+          suggestion: `Use one of the available data columns: ${availableColumns}.${didYouMean(ch.field as string, columnList)}`,
         });
       }
     }
   }
 
+  // Tilemap never reads scale.scheme: fills come from the top-level palette
+  // prop (encoding may be present in both record-map and array-data modes)
+  if (spec.encoding && typeof spec.encoding === 'object') {
+    checkSchemeUnused(
+      spec.encoding as Record<string, unknown>,
+      errors,
+      'tilemap fills come from the top-level palette property',
+      `Remove scale.scheme and set the top-level palette property instead, e.g. palette: "green". Supported: ${MAP_PALETTE_NAMES}.`,
+    );
+  }
+
   // Validate darkMode if provided
   if (spec.darkMode !== undefined && !VALID_DARK_MODES.has(spec.darkMode as string)) {
     errors.push({
@@ -1346,6 +1504,19 @@ function validateMapSpec(spec: Record<string, unknown>, errors: ValidationError[
     return;
   }
 
+  // Map color channels resolve scale.scheme against the sequential palettes
+  // with a silent blue fallback; reject unsupported names here instead.
+  const mapEncoding = spec.encoding as Record<string, unknown>;
+  if (mapEncoding.color && typeof mapEncoding.color === 'object') {
+    checkMapSchemeName(mapEncoding.color as Record<string, unknown>, 'encoding.color', errors);
+  }
+  if (spec.points && typeof spec.points === 'object') {
+    const pointsLayer = spec.points as Record<string, unknown>;
+    if (pointsLayer.color && typeof pointsLayer.color === 'object') {
+      checkMapSchemeName(pointsLayer.color as Record<string, unknown>, 'points.color', errors);
+    }
+  }
+
   // Validate geo.focus if present
   if ('focus' in geo && geo.focus !== undefined && geo.focus !== null) {
     const focus = geo.focus;
@@ -1364,13 +1535,40 @@ function validateMapSpec(spec: Record<string, unknown>, errors: ValidationError[
       }
     } else if (typeof focus === 'object') {
       const focusObj = focus as Record<string, unknown>;
-      if (!('features' in focusObj) || focusObj.features == null) {
+      if ('points' in focusObj) {
+        // Points form: { points: true | { field, value }, padding? } fits the
+        // point layer's cluster (all points, or a matching subset).
+        const pts = focusObj.points;
+        const isSubset =
+          typeof pts === 'object' &&
+          pts !== null &&
+          typeof (pts as Record<string, unknown>).field === 'string' &&
+          'value' in (pts as Record<string, unknown>);
+        if (pts !== true && !isSubset) {
+          errors.push({
+            message:
+              'Spec error: geo.focus.points must be true or { field: string, value: string | number }',
+            path: 'geo.focus.points',
+            code: 'INVALID_TYPE',
+            suggestion:
+              'Use { points: true } to fit all points, or { points: { field: "rating", value: "F" } } to fit a subset.',
+          });
+        }
+        if (focusObj.padding !== undefined && typeof focusObj.padding !== 'number') {
+          errors.push({
+            message: 'Spec error: geo.focus.padding must be a number',
+            path: 'geo.focus.padding',
+            code: 'INVALID_TYPE',
+            suggestion: 'Provide padding as a number in map-local units, e.g. padding: 16',
+          });
+        }
+      } else if (!('features' in focusObj) || focusObj.features == null) {
         errors.push({
-          message: 'Spec error: geo.focus object must have a "features" property',
+          message: 'Spec error: geo.focus object must have a "features" or "points" property',
           path: 'geo.focus.features',
           code: 'MISSING_FIELD',
           suggestion:
-            'Provide feature id(s) to focus on, e.g. geo: { focus: { features: "36", padding: 32 } }',
+            'Provide feature id(s) to focus on, e.g. { features: "36", padding: 32 }, or { points: true } to fit the point cluster.',
         });
       } else {
         const feats = focusObj.features;
@@ -1406,36 +1604,112 @@ function validateMapSpec(spec: Record<string, unknown>, errors: ValidationError[
     } else {
       errors.push({
         message:
-          'Spec error: geo.focus must be a string, number, array of ids, or object with { features, padding? }',
+          'Spec error: geo.focus must be a string, number, array of ids, or object with { features, padding? } or { points: true, padding? }',
         path: 'geo.focus',
         code: 'INVALID_TYPE',
         suggestion:
-          'Use a feature id, array of ids, or { features: "36", padding: 16 }. Pass null to clear focus.',
+          'Use a feature id, array of ids, { features: "36", padding: 16 }, or { points: true }. Pass null to clear focus.',
       });
     }
   }
 
   const encoding = spec.encoding as Record<string, unknown>;
-  for (const channel of ['key', 'color'] as const) {
-    const ch = encoding[channel] as Record<string, unknown> | undefined;
-    if (!ch || typeof ch !== 'object') {
+  const hasPoints = spec.points && typeof spec.points === 'object' && !Array.isArray(spec.points);
+
+  // key is required unless basemap-only mode (points present + empty/no choropleth data)
+  const specData = spec.data as unknown[] | undefined;
+  const isBasemapOnly = hasPoints && (!specData || specData.length === 0);
+  const keyCh = encoding.key as Record<string, unknown> | undefined;
+  if (!isBasemapOnly) {
+    if (!keyCh || typeof keyCh !== 'object') {
       errors.push({
-        message: `Spec error: map encoding requires "${channel}" channel`,
-        path: `encoding.${channel}`,
+        message: 'Spec error: map encoding requires "key" channel',
+        path: 'encoding.key',
         code: 'MISSING_FIELD',
-        suggestion: `Add encoding.${channel}, e.g. ${channel}: { field: "${channel === 'key' ? 'id' : 'value'}", type: "${channel === 'key' ? 'nominal' : 'quantitative'}" }`,
+        suggestion: 'Add encoding.key, e.g. key: { field: "id", type: "nominal" }',
+      });
+    } else if (!keyCh.field || typeof keyCh.field !== 'string') {
+      errors.push({
+        message: 'Spec error: encoding.key must have a "field" string',
+        path: 'encoding.key.field',
+        code: 'MISSING_FIELD',
+        suggestion: 'Add a field name, e.g. key: { field: "id" }',
       });
-      continue;
     }
+  }
 
-    if (!ch.field || typeof ch.field !== 'string') {
+  // color is required UNLESS points is present (basemap-only mode)
+  const colorCh = encoding.color as Record<string, unknown> | undefined;
+  if (!hasPoints) {
+    if (!colorCh || typeof colorCh !== 'object') {
       errors.push({
-        message: `Spec error: encoding.${channel} must have a "field" string`,
-        path: `encoding.${channel}.field`,
+        message:
+          'Spec error: map encoding requires "color" channel (or add a "points" layer for basemap-only mode)',
+        path: 'encoding.color',
         code: 'MISSING_FIELD',
-        suggestion: `Add a field name, e.g. ${channel}: { field: "${channel === 'key' ? 'id' : 'value'}" }`,
+        suggestion: 'Add encoding.color, e.g. color: { field: "value", type: "quantitative" }',
+      });
+    } else if (!colorCh.field || typeof colorCh.field !== 'string') {
+      errors.push({
+        message: 'Spec error: encoding.color must have a "field" string',
+        path: 'encoding.color.field',
+        code: 'MISSING_FIELD',
+        suggestion: 'Add a field name, e.g. color: { field: "value" }',
+      });
+    }
+  } else if (
+    colorCh &&
+    typeof colorCh === 'object' &&
+    (!colorCh.field || typeof colorCh.field !== 'string')
+  ) {
+    errors.push({
+      message: 'Spec error: encoding.color must have a "field" string when provided',
+      path: 'encoding.color.field',
+      code: 'MISSING_FIELD',
+      suggestion: 'Add a field name, e.g. color: { field: "value" }',
+    });
+  }
+
+  // Validate points layer if present
+  if (hasPoints) {
+    const points = spec.points as Record<string, unknown>;
+    if (!Array.isArray(points.data)) {
+      errors.push({
+        message: 'Spec error: points.data must be an array of data rows',
+        path: 'points.data',
+        code: 'INVALID_TYPE',
+        suggestion: 'Provide data as an array of objects with lat/lng fields',
       });
     }
+    for (const ch of ['longitude', 'latitude'] as const) {
+      const enc = points[ch] as Record<string, unknown> | undefined;
+      if (!enc || typeof enc !== 'object') {
+        errors.push({
+          message: `Spec error: points requires "${ch}" encoding channel`,
+          path: `points.${ch}`,
+          code: 'MISSING_FIELD',
+          suggestion: `Add points.${ch}, e.g. ${ch}: { field: "${ch === 'longitude' ? 'lon' : 'lat'}", type: "quantitative" }`,
+        });
+      } else if (!enc.field || typeof enc.field !== 'string') {
+        errors.push({
+          message: `Spec error: points.${ch} must have a "field" string`,
+          path: `points.${ch}.field`,
+          code: 'MISSING_FIELD',
+          suggestion: `Add a field name, e.g. ${ch}: { field: "${ch === 'longitude' ? 'lon' : 'lat'}" }`,
+        });
+      }
+    }
+    for (const ch of ['size', 'color', 'key'] as const) {
+      const enc = points[ch] as Record<string, unknown> | undefined;
+      if (enc && typeof enc === 'object' && (!enc.field || typeof enc.field !== 'string')) {
+        errors.push({
+          message: `Spec error: points.${ch} must have a "field" string when provided`,
+          path: `points.${ch}.field`,
+          code: 'MISSING_FIELD',
+          suggestion: `Add a field name, e.g. ${ch}: { field: "myField" }`,
+        });
+      }
+    }
   }
 }
 
@@ -1490,7 +1764,8 @@ function validateBarListSpec(spec: Record<string, unknown>, errors: ValidationEr
 
   const encoding = spec.encoding as Record<string, unknown>;
   const dataColumns = new Set(Object.keys(firstRow as Record<string, unknown>));
-  const availableColumns = [...dataColumns].join(', ');
+  const columnList = [...dataColumns];
+  const availableColumns = columnList.join(', ');
 
   for (const channel of ['label', 'value'] as const) {
     const ch = encoding[channel] as Record<string, unknown> | undefined;
@@ -1499,7 +1774,7 @@ function validateBarListSpec(spec: Record<string, unknown>, errors: ValidationEr
         message: `Spec error: barlist encoding requires "${channel}" channel`,
         path: `encoding.${channel}`,
         code: 'MISSING_FIELD',
-        suggestion: `Add encoding.${channel} with a field from your data (${availableColumns}). Example: ${channel}: { field: "${[...dataColumns][0] ?? 'myField'}", type: "${channel === 'value' ? 'quantitative' : 'nominal'}" }`,
+        suggestion: `Add encoding.${channel} with a field from your data (${availableColumns}). Example: ${channel}: { field: "${columnList[0] ?? 'myField'}", type: "${channel === 'value' ? 'quantitative' : 'nominal'}" }`,
       });
       continue;
     }
@@ -1519,7 +1794,7 @@ function validateBarListSpec(spec: Record<string, unknown>, errors: ValidationEr
         message: `Spec error: encoding.${channel}.field "${ch.field}" does not exist in data. Available columns: ${availableColumns}`,
         path: `encoding.${channel}.field`,
         code: 'DATA_FIELD_MISSING',
-        suggestion: `Use one of the available data columns: ${availableColumns}`,
+        suggestion: `Use one of the available data columns: ${availableColumns}.${didYouMean(ch.field as string, columnList)}`,
       });
     }
   }
@@ -1534,11 +1809,19 @@ function validateBarListSpec(spec: Record<string, unknown>, errors: ValidationEr
         message: `Spec error: encoding.${channel}.field "${field}" does not exist in data. Available columns: ${availableColumns}`,
         path: `encoding.${channel}.field`,
         code: 'DATA_FIELD_MISSING',
-        suggestion: `Use one of the available data columns: ${availableColumns}`,
+        suggestion: `Use one of the available data columns: ${availableColumns}.${didYouMean(field, columnList)}`,
       });
     }
   }
 
+  // Barlist never reads scale.scheme: bars cycle the built-in barlist palette
+  checkSchemeUnused(
+    encoding,
+    errors,
+    'bar list colors cycle the built-in barlist palette',
+    'Remove scale.scheme. Bar list colors are not configurable via encoding; they cycle the built-in palette.',
+  );
+
   if (spec.darkMode !== undefined && !VALID_DARK_MODES.has(spec.darkMode as string)) {
     errors.push({
       message: 'Spec error: darkMode must be "auto", "force", or "off"',