@adobe/spacecat-shared-data-access 2.99.0 → 2.100.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [@adobe/spacecat-shared-data-access-v2.100.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v2.99.0...@adobe/spacecat-shared-data-access-v2.100.0) (2026-02-02)
+
+
+### Features
+
+* **data-access:** add type-specific data schemas for suggestions [SITES-39183] ([#1289](https://github.com/adobe/spacecat-shared/issues/1289)) ([9824b22](https://github.com/adobe/spacecat-shared/commit/9824b22bc494467849a2ae903ce902ed3f9fde80))
+
 # [@adobe/spacecat-shared-data-access-v2.99.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v2.98.0...@adobe/spacecat-shared-data-access-v2.99.0) (2026-01-30)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/spacecat-shared-data-access",
-  "version": "2.99.0",
+  "version": "2.100.0",
   "description": "Shared modules of the Spacecat Services - Data Access",
   "type": "module",
   "engines": {

package/src/models/suggestion/index.js

@@ -17,3 +17,6 @@ export {
   Suggestion,
   SuggestionCollection,
 };
+
+// Export DATA_SCHEMAS for api-service to reference
+export const { DATA_SCHEMAS } = Suggestion;

package/src/models/suggestion/suggestion.data-schemas.js

@@ -0,0 +1,541 @@
+/*
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+/**
+ * @fileoverview Type-specific data schemas for suggestion opportunity types.
+ * Defines validation schemas and projection configurations.
+ *
+ * Validation schemas should be used in audit-worker when creating/updating suggestions
+ * to ensure data structure consistency before writing to the database.
+ */
+
+import Joi from 'joi';
+import { OPPORTUNITY_TYPES } from '@adobe/spacecat-shared-utils';
+
+/**
+ * Data schemas configuration per opportunity type.
+ *
+ * @typedef {Object} OpportunityTypeSchema
+ * @property {import('joi').Schema} schema - Joi validation schema for the data field
+ * @property {Object} projections - Projection configurations
+ * @property {Object} projections.minimal - Minimal view configuration
+ * @property {string[]} projections.minimal.fields - Fields to include in minimal view
+ * @property {Object<string, string>} projections.minimal.transformers - Field transformers to apply
+ *
+ * @type {Object<string, OpportunityTypeSchema>}
+ *
+ * @example Adding a new opportunity type
+ * [OPPORTUNITY_TYPES.YOUR_TYPE]: {
+ *   schema: Joi.object({
+ *     url: Joi.string().uri().required(),        // Required - in minimal view
+ *     customField: Joi.string().required(),      // Required - in minimal view
+ *     optionalField: Joi.string().optional()     // Optional - not in minimal view
+ *   }).unknown(true),
+ *   projections: {
+ *     minimal: {
+ *       fields: ['url', 'customField'],
+ *       transformers: { customField: 'myTransformerName' }
+ *     }
+ *   }
+ * }
+ */
+export const DATA_SCHEMAS = {
+  [OPPORTUNITY_TYPES.STRUCTURED_DATA]: {
+    schema: Joi.object({
+      url: Joi.string().uri().required(),
+      type: Joi.string().optional(),
+      errors: Joi.array().items(Joi.object()).optional(),
+    }).unknown(true),
+    projections: {
+      minimal: {
+        fields: ['url'],
+        transformers: {},
+      },
+    },
+  },
+  [OPPORTUNITY_TYPES.COLOR_CONTRAST]: {
+    schema: Joi.object({
+      type: Joi.string().optional(),
+      url: Joi.string().uri().required(),
+      issues: Joi.array().items(
+        Joi.object({
+          wcagLevel: Joi.string().optional(),
+          severity: Joi.string().optional(),
+          occurrences: Joi.number().optional(),
+          htmlWithIssues: Joi.array().items(Joi.object()).optional(),
+          failureSummary: Joi.string().optional(),
+          wcagRule: Joi.string().optional(),
+          description: Joi.string().optional(),
+          type: Joi.string().optional(),
+        }).unknown(true),
+      ).required(),
+      jiraLink: Joi.string().uri().allow(null).optional(),
+      aggregationKey: Joi.string().optional(),
+    }).unknown(true),
+    projections: {
+      minimal: {
+        fields: ['url', 'issues'],
+        transformers: {
+          issues: 'filterIssuesOccurrences',
+        },
+      },
+    },
+  },
+  [OPPORTUNITY_TYPES.A11Y_ASSISTIVE]: {
+    schema: Joi.object({
+      type: Joi.string().optional(),
+      url: Joi.string().uri().required(),
+      issues: Joi.array().items(
+        Joi.object({
+          wcagLevel: Joi.string().optional(),
+          severity: Joi.string().optional(),
+          occurrences: Joi.number().optional(),
+          htmlWithIssues: Joi.array().items(Joi.object()).optional(),
+          failureSummary: Joi.string().optional(),
+          wcagRule: Joi.string().optional(),
+          description: Joi.string().optional(),
+          type: Joi.string().optional(),
+        }).unknown(true),
+      ).required(),
+      jiraLink: Joi.string().uri().allow(null).optional(),
+      aggregationKey: Joi.string().optional(),
+    }).unknown(true),
+    projections: {
+      minimal: {
+        fields: ['url', 'issues'],
+        transformers: {
+          issues: 'filterIssuesOccurrences',
+        },
+      },
+    },
+  },
+  [OPPORTUNITY_TYPES.CWV]: {
+    schema: Joi.object({
+      type: Joi.string().required(),
+      url: Joi.string().uri().required(),
+      pageviews: Joi.number().optional(),
+      organic: Joi.number().optional(),
+      metrics: Joi.array().items(
+        Joi.object({
+          deviceType: Joi.string().optional(),
+          pageviews: Joi.number().optional(),
+          clsCount: Joi.number().optional(),
+          ttfbCount: Joi.number().optional(),
+          lcp: Joi.number().optional(),
+          inpCount: Joi.number().optional(),
+          inp: Joi.number().optional(),
+          ttfb: Joi.number().optional(),
+          cls: Joi.number().optional(),
+          lcpCount: Joi.number().optional(),
+          organic: Joi.number().optional(),
+        }).unknown(true),
+      ).required(),
+      issues: Joi.array().items(Joi.object()).required(),
+      aggregationKey: Joi.string().allow(null).optional(),
+    }).unknown(true),
+    projections: {
+      minimal: {
+        fields: ['url', 'type', 'metrics', 'issues'],
+        transformers: {
+          metrics: 'filterCwvMetrics',
+        },
+      },
+    },
+  },
+  [OPPORTUNITY_TYPES.ALT_TEXT]: {
+    schema: Joi.object({
+      recommendations: Joi.array().items(
+        Joi.object({
+          isAppropriate: Joi.boolean().optional(),
+          isDecorative: Joi.boolean().optional(),
+          xpath: Joi.string().optional(),
+          altText: Joi.string().optional(),
+          imageUrl: Joi.string().uri().optional(),
+          pageUrl: Joi.string().uri().optional(),
+          language: Joi.string().optional(),
+          id: Joi.string().optional(),
+        }).unknown(true),
+      ).required(),
+      aggregationKey: Joi.string().allow(null).optional(),
+    }).unknown(true),
+    projections: {
+      minimal: {
+        fields: ['recommendations'],
+        transformers: {
+          recommendations: 'extractPageUrlFromRecommendations',
+        },
+      },
+    },
+  },
+  [OPPORTUNITY_TYPES.SECURITY_PERMISSIONS]: {
+    schema: Joi.object({
+      principal: Joi.string().optional(),
+      path: Joi.string().required(),
+      issue: Joi.string().optional(),
+      permissions: Joi.array().items(Joi.string()).optional(),
+      recommended_permissions: Joi.array().items(Joi.string()).optional(),
+      acl: Joi.array().items(Joi.string()).optional(),
+      otherPermissions: Joi.array().optional(),
+      rationale: Joi.string().optional(),
+      aggregationKey: Joi.string().allow(null).optional(),
+    }).unknown(true),
+    projections: {
+      minimal: {
+        fields: ['path'],
+        transformers: {},
+      },
+    },
+  },
+  [OPPORTUNITY_TYPES.SECURITY_VULNERABILITIES]: {
+    schema: Joi.object({
+      current_version: Joi.string().optional(),
+      library: Joi.string().optional(),
+      recommended_version: Joi.string().allow(null).optional(),
+      cves: Joi.array().items(
+        Joi.object({
+          summary: Joi.string().optional(),
+          score: Joi.number().optional(),
+          score_text: Joi.string().optional(),
+          cve_id: Joi.string().optional(),
+          url: Joi.string().uri().optional(),
+        }).unknown(true),
+      ).required(),
+      aggregationKey: Joi.string().allow(null).optional(),
+    }).unknown(true),
+    projections: {
+      minimal: {
+        fields: ['cves'],
+        transformers: {
+          cves: 'extractCveUrls',
+        },
+      },
+    },
+  },
+  [OPPORTUNITY_TYPES.FORM_ACCESSIBILITY]: {
+    schema: Joi.object({
+      source: Joi.string().required(),
+      type: Joi.string().optional(),
+      aiGenerated: Joi.boolean().optional(),
+      url: Joi.string().uri().required(),
+      issues: Joi.array().items(
+        Joi.object({
+          wcagLevel: Joi.string().optional(),
+          severity: Joi.string().optional(),
+          occurrences: Joi.number().optional(),
+          htmlWithIssues: Joi.array().items(Joi.object()).optional(),
+          failureSummary: Joi.string().optional(),
+          wcagRule: Joi.string().optional(),
+          understandingUrl: Joi.string().uri().optional(),
+          description: Joi.string().optional(),
+          type: Joi.string().optional(),
+        }).unknown(true),
+      ).required(),
+      jiraLink: Joi.string().uri().allow(null).optional(),
+      aggregationKey: Joi.string().optional(),
+    }).unknown(true),
+    projections: {
+      minimal: {
+        fields: ['url', 'source', 'issues'],
+        transformers: {
+          issues: 'filterIssuesOccurrences',
+        },
+      },
+    },
+  },
+  [OPPORTUNITY_TYPES.CANONICAL]: {
+    schema: Joi.object({
+      url: Joi.string().uri().required(),
+      checkType: Joi.string().optional(),
+      type: Joi.string().optional(),
+      suggestion: Joi.string().optional(),
+      recommendedAction: Joi.string().optional(),
+      explanation: Joi.string().optional(),
+      aggregationKey: Joi.string().allow(null).optional(),
+    }).unknown(true),
+    projections: {
+      minimal: {
+        fields: ['url'],
+        transformers: {},
+      },
+    },
+  },
+  [OPPORTUNITY_TYPES.HEADINGS]: {
+    schema: Joi.object({
+      url: Joi.string().uri().required(),
+      type: Joi.string().optional(),
+      checkType: Joi.string().optional(),
+      explanation: Joi.string().optional(),
+      recommendedAction: Joi.string().optional(),
+      checkTitle: Joi.string().optional(),
+      isAISuggested: Joi.boolean().optional(),
+      transformRules: Joi.object().optional(),
+      aggregationKey: Joi.string().allow(null).optional(),
+    }).unknown(true),
+    projections: {
+      minimal: {
+        fields: ['url'],
+        transformers: {},
+      },
+    },
+  },
+  [OPPORTUNITY_TYPES.HREFLANG]: {
+    schema: Joi.object({
+      url: Joi.string().uri().required(),
+      type: Joi.string().optional(),
+      checkType: Joi.string().optional(),
+      explanation: Joi.string().optional(),
+      recommendedAction: Joi.string().optional(),
+      suggestion: Joi.string().allow(null).optional(),
+      aggregationKey: Joi.string().allow(null).optional(),
+    }).unknown(true),
+    projections: {
+      minimal: {
+        fields: ['url'],
+        transformers: {},
+      },
+    },
+  },
+  [OPPORTUNITY_TYPES.INVALID_OR_MISSING_METADATA]: {
+    schema: Joi.object({
+      url: Joi.string().uri().required(),
+      tagName: Joi.string().optional(),
+      issue: Joi.string().optional(),
+      tagContent: Joi.string().allow('', null).optional(),
+      rank: Joi.number().optional(),
+      seoRecommendation: Joi.string().optional(),
+      issueDetails: Joi.string().optional(),
+      seoImpact: Joi.string().optional(),
+      aiRationale: Joi.string().optional(),
+      aiSuggestion: Joi.string().optional(),
+      aggregationKey: Joi.string().allow(null).optional(),
+    }).unknown(true),
+    projections: {
+      minimal: {
+        fields: ['url'],
+        transformers: {},
+      },
+    },
+  },
+  [OPPORTUNITY_TYPES.SITEMAP]: {
+    schema: Joi.object({
+      sitemapUrl: Joi.string().uri().required(),
+      pageUrl: Joi.string().uri().required(),
+      type: Joi.string().valid('url', 'error').optional(),
+      statusCode: Joi.number().optional(),
+      urlsSuggested: Joi.string().uri().optional(),
+      recommendedAction: Joi.string().optional(),
+      error: Joi.string().optional(),
+      aggregationKey: Joi.string().allow(null).optional(),
+    }).unknown(true),
+    projections: {
+      minimal: {
+        fields: ['sitemapUrl', 'pageUrl'],
+        transformers: {},
+      },
+    },
+  },
+  [OPPORTUNITY_TYPES.BROKEN_BACKLINKS]: {
+    schema: Joi.object({
+      url_from: Joi.string().uri().required(),
+      url_to: Joi.string().uri().required(),
+      title: Joi.string().optional(),
+      traffic_domain: Joi.number().optional(),
+      aiRationale: Joi.string().optional(),
+      urlsSuggested: Joi.array().items(Joi.string().uri()).optional(),
+      aggregationKey: Joi.string().allow(null).optional(),
+    }).unknown(true),
+    projections: {
+      minimal: {
+        fields: ['url_from', 'url_to'],
+        transformers: {},
+      },
+    },
+  },
+  [OPPORTUNITY_TYPES.BROKEN_INTERNAL_LINKS]: {
+    schema: Joi.object({
+      urlFrom: Joi.string().uri().required(),
+      urlTo: Joi.string().uri().required(),
+      title: Joi.string().optional(),
+      urlsSuggested: Joi.array().items(Joi.string().uri()).optional(),
+      aiRationale: Joi.string().optional(),
+      trafficDomain: Joi.number().optional(),
+      priority: Joi.string().optional(),
+      aggregationKey: Joi.string().allow(null).optional(),
+    }).unknown(true),
+    projections: {
+      minimal: {
+        fields: ['urlFrom', 'urlTo'],
+        transformers: {},
+      },
+    },
+  },
+  [OPPORTUNITY_TYPES.PRERENDER]: {
+    schema: Joi.object({
+      url: Joi.string().uri().required(),
+      contentGainRatio: Joi.number().optional(),
+      wordCountBefore: Joi.number().optional(),
+      wordCountAfter: Joi.number().optional(),
+      originalHtmlKey: Joi.string().optional(),
+      prerenderedHtmlKey: Joi.string().optional(),
+      organicTraffic: Joi.number().optional(),
+      aggregationKey: Joi.string().allow(null).optional(),
+    }).unknown(true),
+    projections: {
+      minimal: {
+        fields: ['url'],
+        transformers: {},
+      },
+    },
+  },
+  [OPPORTUNITY_TYPES.HIGH_ORGANIC_LOW_CTR]: {
+    schema: Joi.object({
+      url: Joi.string().uri().optional(),
+      clicks: Joi.number().optional(),
+      impressions: Joi.number().optional(),
+      ctr: Joi.number().optional(),
+      position: Joi.number().optional(),
+      variations: Joi.array().items(
+        Joi.object({
+          id: Joi.string().optional(),
+          name: Joi.string().optional(),
+          screenshotUrl: Joi.string().uri().optional(),
+          variationPageUrl: Joi.string().uri().optional(),
+          variationEditPageUrl: Joi.string().uri().allow(null).optional(),
+          variationMdPageUrl: Joi.string().uri().allow(null).optional(),
+          previewImage: Joi.string().uri().optional(),
+          explanation: Joi.string().allow(null).optional(),
+          projectedImpact: Joi.number().optional(),
+          changes: Joi.array().optional(),
+          variationChanges: Joi.object({
+            changes: Joi.object({
+              type: Joi.string().optional(),
+              mdUrl: Joi.string().uri().optional(),
+              md: Joi.string().optional(),
+            }).unknown(true).optional(),
+          }).unknown(true).optional(),
+        }).unknown(true),
+      ).optional(),
+      aggregationKey: Joi.string().allow(null).optional(),
+    }).unknown(true),
+    projections: {
+      minimal: {
+        fields: [],
+        transformers: {},
+      },
+    },
+  },
+  [OPPORTUNITY_TYPES.LLM_BLOCKED]: {
+    schema: Joi.object({
+      affectedUserAgents: Joi.array().items(Joi.string()).optional(),
+      lineNumber: Joi.number().optional(),
+      items: Joi.array().items(
+        Joi.object({
+          url: Joi.string().uri().optional(),
+          agent: Joi.string().optional(),
+        }).unknown(true),
+      ).optional(),
+      robotsTxtHash: Joi.string().optional(),
+      url: Joi.string().uri().optional(),
+      pattern: Joi.string().optional(),
+      aggregationKey: Joi.string().allow(null).optional(),
+    }).unknown(true),
+    projections: {
+      minimal: {
+        fields: [],
+        transformers: {},
+      },
+    },
+  },
+  // ========== SCHEMAS NEED VALIDATION ==========
+  // The following schemas exist (taken from audit-worker structure) but have NOT been
+  // validated against actual suggestion data yet.
+  //
+  // TODO: When these opportunity types generate suggestions:
+  //   1. Validate the schema against real suggestion data
+  //   2. Update minimal projection fields to match actual requirements
+  //   3. Add Suggestion.validateData() call in audit-worker when creating suggestions
+  //   4. Make required fields properly marked based on minimal projection
+  //
+  // Schemas needing validation:
+  // - SITEMAP_PRODUCT_COVERAGE
+  // - REDIRECT_CHAINS
+  [OPPORTUNITY_TYPES.SITEMAP_PRODUCT_COVERAGE]: {
+    schema: Joi.object({
+      locale: Joi.string().optional(),
+      url: Joi.string().uri().optional(),
+      recommendedAction: Joi.string().optional(),
+      aggregationKey: Joi.string().allow(null).optional(),
+    }).unknown(true),
+    projections: {
+      minimal: {
+        fields: ['url'],
+        transformers: {},
+      },
+    },
+  },
+  [OPPORTUNITY_TYPES.REDIRECT_CHAINS]: {
+    schema: Joi.object({
+      key: Joi.string().optional(),
+      fixType: Joi.string().optional(),
+      fix: Joi.string().optional(),
+      canApplyFixAutomatically: Joi.boolean().optional(),
+      redirectsFile: Joi.string().optional(),
+      redirectCount: Joi.number().optional(),
+      httpStatusCode: Joi.number().optional(),
+      sourceUrl: Joi.string().uri().optional(),
+      sourceUrlFull: Joi.string().uri().optional(),
+      destinationUrl: Joi.string().uri().optional(),
+      destinationUrlFull: Joi.string().uri().optional(),
+      finalUrl: Joi.string().uri().optional(),
+      finalUrlFull: Joi.string().uri().optional(),
+      ordinalDuplicate: Joi.number().optional(),
+      redirectChain: Joi.array().items(Joi.object()).optional(),
+      errorMsg: Joi.string().optional(),
+      aggregationKey: Joi.string().allow(null).optional(),
+    }).unknown(true),
+    projections: {
+      minimal: {
+        fields: ['sourceUrl', 'destinationUrl', 'finalUrl'],
+        transformers: {},
+      },
+    },
+  },
+
+  // ========== SCHEMAS TO BE ADDED ==========
+  // TODO: The following opportunity types need schemas to be added.
+  // Research actual suggestion data for these types and add schemas following the pattern:
+  //   1. Get real suggestion data examples
+  //   2. Define schema with proper field types
+  //   3. Make minimal projection fields required (urls used for filtering on ASO UI)
+  //   4. Validate against actual data
+  //
+  // Opportunity types pending schema implementation:
+  // - ACCESSIBILITY (parent type - may use A11Y_ASSISTIVE and COLOR_CONTRAST schemas)
+  // - NOTFOUND (404 pages)
+  // - RAGECLICK
+  // - HIGH_INORGANIC_HIGH_BOUNCE_RATE
+  // - HIGH_FORM_VIEWS_LOW_CONVERSIONS
+  // - HIGH_PAGE_VIEWS_LOW_FORM_NAV
+  // - HIGH_PAGE_VIEWS_LOW_FORM_VIEWS
+  // - DETECT_GEO_BRAND_PRESENCE
+  // - DETECT_GEO_BRAND_PRESENCE_DAILY
+  // - GEO_BRAND_PRESENCE_TRIGGER_REFRESH
+  // - GUIDANCE_GEO_FAQ
+  // - SECURITY_CSP (data.findings[].url - for URL filtering)
+  // - SECURITY_XSS (data.link - for URL filtering,
+  //                 may use SECURITY_CSP schema or need separate schema)
+  // - SECURITY_PERMISSIONS_REDUNDANT (may use SECURITY_PERMISSIONS schema
+  //                                   or need separate schema)
+  // - GENERIC_OPPORTUNITY
+  // - PAID_COOKIE_CONSENT
+  // - WIKIPEDIA_ANALYSIS
+};

package/src/models/suggestion/suggestion.model.js

@@ -11,6 +11,8 @@
  */
 
 import BaseModel from '../base/base.model.js';
+import { DATA_SCHEMAS } from './suggestion.data-schemas.js';
+import { FIELD_TRANSFORMERS, FALLBACK_PROJECTION } from './suggestion.projection-utils.js';
 
 /**
  * Suggestion - A class representing a Suggestion entity.
@@ -44,6 +46,71 @@ class Suggestion extends BaseModel {
     CONFIG_UPDATE: 'CONFIG_UPDATE',
   };
 
+  // Import schemas from external file for maintainability
+  static FIELD_TRANSFORMERS = FIELD_TRANSFORMERS;
+
+  static DATA_SCHEMAS = DATA_SCHEMAS;
+
+  static FALLBACK_PROJECTION = FALLBACK_PROJECTION;
+
+  /**
+   * Gets the projection configuration for a given opportunity type and view.
+   * Falls back to FALLBACK_PROJECTION if no schema is defined for the type.
+   *
+   * @param {string} opportunityType - The opportunity type from OPPORTUNITY_TYPES enum
+   * @param {string} [viewName='minimal'] - The view name (e.g., 'minimal', 'summary')
+   * @returns {Object} Projection configuration with fields and transformers
+   *
+   * @example
+   * const projection = Suggestion.getProjection('cwv', 'minimal');
+   * // Returns: { fields: ['url', 'type', 'metrics', 'issues'],
+   * //   transformers: { metrics: 'filterCwvMetrics' } }
+   */
+  static getProjection(opportunityType, viewName = 'minimal') {
+    const schemaConfig = this.DATA_SCHEMAS[opportunityType];
+
+    if (schemaConfig?.projections?.[viewName]) {
+      return schemaConfig.projections[viewName];
+    }
+
+    // Fallback for unknown types
+    return this.FALLBACK_PROJECTION[viewName] || this.FALLBACK_PROJECTION.minimal;
+  }
+
+  /**
+   * Validates suggestion data against the Joi schema for the given opportunity type.
+   * If no schema is defined, validation is skipped (graceful fallback).
+   *
+   * **Usage:** Call this in audit-worker before creating/updating suggestions to ensure
+   * data structure consistency across services.
+   *
+   * @param {Object} data - Suggestion data to validate
+   * @param {string} opportunityType - The opportunity type from OPPORTUNITY_TYPES enum
+   * @throws {Error} If validation fails with details
+   *
+   * @example
+   * // In audit-worker before creating a suggestion:
+   * try {
+   *   Suggestion.validateData({ url: 'https://example.com' }, 'structured-data');
+   *   // Proceed with creating suggestion
+   * } catch (error) {
+   *   log.error('Invalid suggestion data:', error.message);
+   * }
+   */
+  static validateData(data, opportunityType) {
+    const schemaConfig = this.DATA_SCHEMAS[opportunityType];
+
+    if (!schemaConfig?.schema) {
+      // No schema defined, skip validation
+      return;
+    }
+
+    const { error } = schemaConfig.schema.validate(data);
+    if (error) {
+      throw new Error(`Invalid data for opportunity type ${opportunityType}: ${error.message}`);
+    }
+  }
+
   // add your customized method here
 }
 

package/src/models/suggestion/suggestion.projection-utils.js

@@ -0,0 +1,110 @@
+/*
+ * Copyright 2024 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+/**
+ * @fileoverview Utility functions and configurations for suggestion data projections.
+ */
+
+/**
+ * Reusable field transformation functions for projecting suggestion data.
+ * Referenced by name in DATA_SCHEMAS transformer configurations.
+ *
+ * @type {Object<string, Function>}
+ *
+ * @example Usage in DATA_SCHEMAS
+ * projections: {
+ *   minimal: {
+ *     fields: ['issues'],
+ *     transformers: {
+ *       // References FIELD_TRANSFORMERS['filterIssuesOccurrences']
+ *       issues: 'filterIssuesOccurrences'
+ *     }
+ *   }
+ * }
+ */
+export const FIELD_TRANSFORMERS = {
+  /**
+   * Filters issues array to only include occurrences count.
+   * Used for accessibility-related opportunity types.
+   */
+  filterIssuesOccurrences: (issues) => {
+    if (!Array.isArray(issues)) return issues;
+    return issues.map((issue) => ({
+      occurrences: issue.occurrences,
+    }));
+  },
+  /**
+   * Filters metrics array to only include essential CWV fields.
+   * Used for Core Web Vitals opportunity type.
+   */
+  filterCwvMetrics: (metrics) => {
+    if (!Array.isArray(metrics)) return metrics;
+    return metrics.map((metric) => ({
+      deviceType: metric.deviceType,
+      lcp: metric.lcp,
+      inp: metric.inp,
+      cls: metric.cls,
+    }));
+  },
+  /**
+   * Extracts pageUrl from recommendations array.
+   * Used for alt-text opportunity type.
+   */
+  extractPageUrlFromRecommendations: (recommendations) => {
+    if (!Array.isArray(recommendations)) return recommendations;
+    return recommendations.map((rec) => ({
+      pageUrl: rec.pageUrl,
+    }));
+  },
+  /**
+   * Extracts URLs from CVEs array.
+   * Used for security vulnerability opportunity types.
+   */
+  extractCveUrls: (cves) => {
+    if (!Array.isArray(cves)) return cves;
+    return cves.map((cve) => ({
+      url: cve.url,
+    }));
+  },
+};
+
+/**
+ * Default projection configuration for opportunity types without explicit schemas.
+ * Conservative fallback that only includes common URL-related fields.
+ * Forces engineers to define explicit schemas if they need specific data fields.
+ *
+ * @type {Object}
+ * @property {Object} minimal - Minimal view configuration
+ * @property {string[]} minimal.fields - Common URL fields only (13 fields)
+ * @property {Object} minimal.transformers - No transformers applied by default
+ */
+export const FALLBACK_PROJECTION = {
+  minimal: {
+    fields: [
+      'url',
+      'urls',
+      'urlFrom',
+      'urlTo',
+      'url_from',
+      'url_to',
+      'urlsSuggested',
+      'pageUrl',
+      'sitemapUrl',
+      'pattern',
+      'link',
+      'path',
+      'sourceUrl',
+      'destinationUrl',
+    ],
+    transformers: {},
+  },
+};