@jammysunshine/astrology-shared 1.0.1

package/schemas/index.js

@@ -0,0 +1,940 @@
+/**
+ * Modular Schema Management System
+ * Centralizes loading, validation, and registration of JSON Schemas using AJV.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const Ajv = require('ajv');
+const addFormats = require('ajv-formats');
+const logger = require('../logger').default;
+
+// Initialize AJV with moderate validation and proper reference resolution
+const ajv = new Ajv({
+  allErrors: true,           // Report all validation errors
+  removeAdditional: false,   // Don't remove additional properties
+  useDefaults: true,         // Apply default values
+  coerceTypes: false,        // Don't coerce types
+  strict: false,             // Turn off strict mode to allow proper allOf resolution
+  validateFormats: true,     // Still validate format keywords
+  validateSchema: true,      // Validate schema structure
+  // Enable proper reference resolution
+  schemaId: '$id',           // Use $id for schema identification
+  loadSchema: async (uri) => {
+    // Custom schema loading function to handle cross-references
+    const schemaPath = path.join(__dirname, uri.replace('http://localhost/schemas/', ''));
+    try {
+      return JSON.parse(fs.readFileSync(schemaPath, 'utf8'));
+    } catch (e) {
+      throw new Error(`Failed to load schema ${uri}: ${e.message}`);
+    }
+  }
+});
+
+// Add AJV plugins for better reference resolution
+require('ajv/lib/refs/json-schema-draft-07.json'); // Load standard schema definition
+
+// Add common formats like date-time, uuid, email, etc.
+addFormats(ajv);
+
+// Enhanced cache for loaded schemas and compiled validators with TTL
+const schemaCache = new Map();
+const validatorCache = new Map();
+const schemaCacheTimestamps = new Map();
+const validatorCacheTimestamps = new Map();
+
+/**
+ * High-performance iterative deep clone utility optimized for schema validation.
+ * Mimics JSON serialization behavior (Dates to strings, removes undefined/functions)
+ * but avoids the overhead of full stringification and recursion stack overflows.
+ */
+function fastClone(input) {
+  if (input === null) {
+    return input;
+  }
+
+  if (input instanceof Date) {
+    return input.toISOString();
+  }
+
+  if (typeof input !== 'object') {
+    return input;
+  }
+
+  const result = Array.isArray(input) ? [] : {};
+  const stack = [{ source: input, target: result }];
+  const seen = new WeakMap();
+
+  if (typeof input === 'object' && input !== null) {
+    seen.set(input, result);
+  }
+
+  while (stack.length > 0) {
+    const { source, target } = stack.pop();
+
+    for (const key in source) {
+      if (!Object.prototype.hasOwnProperty.call(source, key)) continue;
+
+      const value = source[key];
+
+      if (value === undefined || typeof value === 'function') continue;
+
+      if (value === null || typeof value !== 'object') {
+        target[key] = value;
+        continue;
+      }
+
+      // Handle Date objects
+      if (value instanceof Date) {
+        target[key] = value.toISOString();
+        continue;
+      }
+
+      // Handle circular references or already processed objects
+      if (seen.has(value)) {
+        target[key] = seen.get(value);
+        continue;
+      }
+
+      const newValue = Array.isArray(value) ? [] : {};
+      target[key] = newValue;
+      seen.set(value, newValue);
+      stack.push({ source: value, target: newValue });
+    }
+  }
+
+  return result;
+}
+
+// Cache TTL settings (in milliseconds)
+const SCHEMA_CACHE_TTL = process.env.SCHEMA_CACHE_TTL || 3600000; // 1 hour default
+const VALIDATOR_CACHE_TTL = process.env.VALIDATOR_CACHE_TTL || 3600000; // 1 hour default
+
+// Method-to-schema mapping registry for automatic resolution
+const methodSchemaMappings = new Map();
+
+// Cache management functions
+function isCacheExpired(cacheTimestamps, key, ttl) {
+  const timestamp = cacheTimestamps.get(key);
+  if (!timestamp) return true;
+  return (Date.now() - timestamp) > ttl;
+}
+
+function getCachedSchema(key) {
+  if (isCacheExpired(schemaCacheTimestamps, key, SCHEMA_CACHE_TTL)) {
+    schemaCache.delete(key);
+    schemaCacheTimestamps.delete(key);
+    return null;
+  }
+  return schemaCache.get(key);
+}
+
+function setCachedSchema(key, schema) {
+  schemaCache.set(key, schema);
+  schemaCacheTimestamps.set(key, Date.now());
+}
+
+function getCachedValidator(key) {
+  if (isCacheExpired(validatorCacheTimestamps, key, VALIDATOR_CACHE_TTL)) {
+    validatorCache.delete(key);
+    validatorCacheTimestamps.delete(key);
+    return null;
+  }
+  return validatorCache.get(key);
+}
+
+function setCachedValidator(key, validator) {
+  validatorCache.set(key, validator);
+  validatorCacheTimestamps.set(key, Date.now());
+}
+
+// Strict validation mode (can be controlled via environment)
+
+// Schema version management
+const schemaVersions = new Map();
+const schemaVersionHistory = new Map();
+
+function registerSchemaVersion(schemaName, version, schemaDefinition) {
+  const key = `${schemaName}@${version}`;
+  schemaVersions.set(key, schemaDefinition);
+  schemaVersionHistory.set(schemaName, version);
+}
+
+function getSchemaVersion(schemaName, version = 'latest') {
+  if (version === 'latest') {
+    version = schemaVersionHistory.get(schemaName) || 'v1';
+  }
+  const key = `${schemaName}@${version}`;
+  return schemaVersions.get(key);
+}
+
+function getSchemaVersionHistory(schemaName) {
+  return schemaVersionHistory.get(schemaName);
+}
+
+// Method-to-schema mapping functions
+function registerMethodSchemaMapping(serviceName, methodName, schemas) {
+  const key = `${serviceName}.${methodName}`;
+  methodSchemaMappings.set(key, schemas);
+}
+
+function getMethodSchemaMapping(serviceName, methodName) {
+  const key = `${serviceName}.${methodName}`;
+  return methodSchemaMappings.get(key);
+}
+
+function getValidationSchemas(serviceName, methodName) {
+  // First try explicit method mapping
+  const methodMapping = getMethodSchemaMapping(serviceName, methodName);
+  if (methodMapping) {
+    return methodMapping;
+  }
+
+  // Fallback to automatic resolution based on service and method patterns
+  const inputSchema = getAutomaticInputSchema(serviceName, methodName);
+  const outputSchema = getAutomaticOutputSchema(serviceName, methodName);
+  const dataSchema = getAutomaticDataSchema(serviceName, methodName);
+  const errorSchema = getAutomaticErrorSchema(serviceName, methodName);
+
+  return {
+    inputSchema,
+    outputSchema,
+    dataSchema,
+    errorSchema
+  };
+}
+
+function getAutomaticInputSchema(serviceName, methodName) {
+  // First check if service has a registered schema category
+  const registeredSchemaCategory = serviceSchemaMap.get(serviceName);
+  const schemaCategory = registeredSchemaCategory ||
+                         serviceNameToSchemaCategory[serviceName] ||
+                         'default';
+
+  if (schemaCategory !== 'default') {
+    const schemaName = schemaCategoryToSchemaName[schemaCategory];
+    if (schemaName) {
+      return schemaName;
+    }
+  }
+
+  // Fallback to automatic mapping based on service type
+  if (serviceName.toLowerCase().includes('birth') || serviceName.toLowerCase().includes('chart')) {
+    return 'astrology/vedic/input';
+  } else if (serviceName.toLowerCase().includes('dasha')) {
+    return 'astrology/vedic/input';
+  } else if (serviceName.toLowerCase().includes('compatibility')) {
+    return 'astrology/compatibility/input';
+  }
+  return 'astrology/vedic/input'; // Default
+}
+
+function getAutomaticOutputSchema(serviceName, methodName) {
+  // Automatic mapping based on service type
+  if (serviceName.toLowerCase().includes('birth') || serviceName.toLowerCase().includes('chart')) {
+    return 'v1/domains/astrology/services/birth-chart/service.v1.json';
+  } else if (serviceName.toLowerCase().includes('dasha')) {
+    return 'v1/domains/astrology/services/dasha/service.v1.json';
+  }
+  return 'v1/domains/astrology/services/birth-chart/service.v1.json'; // Default
+}
+
+function getAutomaticDataSchema(serviceName, methodName) {
+  // Automatic mapping based on service type for data schemas
+  if (serviceName.toLowerCase().includes('birth') || serviceName.toLowerCase().includes('chart')) {
+    return 'astrology/birth-chart-data';
+  } else if (serviceName.toLowerCase().includes('dasha')) {
+    return 'astrology/dasha-data';
+  }
+  return 'astrology/birth-chart-data'; // Default
+}
+
+function getAutomaticErrorSchema(serviceName, methodName) {
+  return 'v1/shared/error.v1.json';
+}
+
+/**
+ * Hardcoded schema registry - maps schema names to file paths.
+ * @returns {object} Schema registry object.
+ */
+function getRegistry() {
+  return {
+    services: {
+       astrology: {
+           'birth-chart': {
+             service: { path: 'v1/domains/astrology/services/birth-chart/service.v1.json' }
+           },
+           dasha: {
+             service: { path: 'v1/domains/astrology/services/dasha/service.v1.json' }
+           },
+           sessionManager: {
+             service: { path: 'v1/domains/astrology/components/session-data.v1.json' }
+           },
+           astrologer: { // Assuming astrologer service uses vedic input for its service schema
+             v1: { path: 'v1/domains/astrology/inputs/vedic.v1.json' },
+             service: { path: 'v1/domains/astrology/inputs/vedic.v1.json' }
+           },
+         vedic: {
+          input: {
+            v1: { path: 'v1/domains/astrology/inputs/vedic.v1.json' }
+          }
+        },
+        compatibility: {
+          input: {
+            v1: { path: 'v1/domains/astrology/inputs/compatibility.v1.json' }
+          }
+        }
+      }
+    },
+    components: {
+      astrology: {
+        planet: { path: 'v1/domains/astrology/components/planet.json' },
+        house: { path: 'v1/domains/astrology/components/house.json' },
+        aspect: { path: 'v1/domains/astrology/components/aspect.json' },
+        'dasha-period': { path: 'v1/domains/astrology/components/dasha-period.v1.json' },
+        'birth-data': { path: 'v1/domains/astrology/components/birthData.json' },
+        'user-data': { path: 'v1/domains/astrology/components/user-data.v1.json' },
+        'session-data': { path: 'v1/domains/astrology/components/session-data.v1.json' },
+        'birth-chart-data': { path: 'v1/domains/astrology/services/birth-chart/data.v1.json' },
+        'dasha-data': { path: 'v1/domains/astrology/services/dasha/data.v1.json' }
+      },
+      shared: {
+        metadata: { path: 'v1/shared/metadata.v1.json' },
+        error: { path: 'v1/shared/error.v1.json' },
+        performance: { path: 'v1/shared/performance.v1.json' },
+        'client-context': { path: 'v1/shared/client-context.v1.json' },
+        preferences: { path: 'v1/shared/preferences.v1.json' },
+        'platform-context': { path: 'v1/shared/PlatformContext.json' },
+        'response-metadata': { path: 'v1/shared/ResponseMetadata.json' },
+        'platform-user-id': { path: 'v1/shared/PlatformUserId.json' },
+        observability: { path: 'v1/services/observability/query.v1.json' },
+        'astrology/birthData': { path: 'v1/domains/astrology/components/birthData.json' },
+        sessionManager: { path: 'v1/domains/astrology/components/session-data.v1.json' },
+        dasha: { path: 'v1/domains/astrology/services/dasha/service.v1.json' },
+        birthchart: { path: 'v1/domains/astrology/services/birth-chart/service.v1.json' }
+      },
+      services: {
+        'ai-query': { path: 'v1/services/ai/query.v1.json' },
+        'database-query': { path: 'v1/services/database/query.v1.json' },
+        'location-query': { path: 'v1/services/location/query.v1.json' },
+        'logging-entry': { path: 'v1/services/logging/entry.v1.json' },
+        'observability-query': { path: 'v1/services/observability/query.v1.json' },
+        'observability-record': { path: 'v1/services/observability/record-metric.v1.json' },
+        'cache-query': { path: 'v1/services/cache/query.v1.json' }
+      }
+    }
+  };
+}
+
+// Register explicit method-to-schema mappings
+registerMethodSchemaMapping('observability', 'recordBusinessMetric', {
+  inputSchema: 'v1/services/observability/record-metric.v1.json',
+  outputSchema: 'v1/shared/ResponseMetadata.json'
+});
+registerMethodSchemaMapping('observability', 'recordMetric', {
+  inputSchema: 'v1/services/observability/record-metric.v1.json',
+  outputSchema: 'v1/shared/ResponseMetadata.json'
+});
+registerMethodSchemaMapping('observability', 'getMetrics', {
+  inputSchema: 'v1/services/observability/query.v1.json',
+  outputSchema: 'v1/shared/ResponseMetadata.json'
+});
+
+function preloadSchemas() {
+  const registry = getRegistry();
+
+  // Define schema dependencies to ensure proper loading order
+  const schemaDependencies = {
+    'v1/domains/astrology/inputs/vedic.v1.json': [
+      'v1/shared/PlatformContext.json',
+      'v1/shared/PlatformUserId.json',
+      'v1/domains/astrology/components/user-data.v1.json',
+      'v1/shared/preferences.v1.json',
+      'v1/domains/astrology/components/birthData.json'
+    ],
+    // Add other dependencies as needed
+  };
+
+  const schemasToLoad = [];
+
+  // Helper to collect schemas, ensuring the 'path' is used as the ID
+  const collectSchemas = (obj) => {
+    if (!obj || typeof obj !== 'object') return;
+    for (const key of Object.keys(obj)) {
+      if (typeof obj[key] === 'object' && obj[key] !== null) {
+        if (obj[key].path) { // If this object directly has a path, it's a schema entry
+          schemasToLoad.push({ path: obj[key].path });
+        } else { // Otherwise, recurse deeper
+          collectSchemas(obj[key]);
+        }
+      }
+    }
+  };
+
+  // Initial calls to collectSchemas - load shared schemas first (referenced by others)
+  collectSchemas(registry.components); // This includes shared schemas
+  collectSchemas(registry.services); // Service schemas reference shared schemas
+
+  // Sort schemas to ensure dependencies are loaded first
+  const sortedSchemas = [];
+  const processedSchemas = new Set();
+
+  const addSchemaWithDependencies = (schemaPath) => {
+    if (processedSchemas.has(schemaPath)) return;
+
+    // Process dependencies first
+    const dependencies = schemaDependencies[schemaPath] || [];
+    for (const dep of dependencies) {
+      if (!processedSchemas.has(dep)) {
+        addSchemaWithDependencies(dep);
+      }
+    }
+
+    // Then add the schema itself
+    sortedSchemas.push({ path: schemaPath });
+    processedSchemas.add(schemaPath);
+  };
+
+  // Process all schemas with dependency resolution
+  for (const schemaData of schemasToLoad) {
+    addSchemaWithDependencies(schemaData.path);
+  }
+
+  for (const schemaData of sortedSchemas) {
+    const fullPath = path.join(__dirname, schemaData.path);
+    try {
+      let schema = JSON.parse(fs.readFileSync(fullPath, 'utf8'));
+
+      // Ensure all schemas have an $id for proper reference resolution within AJV
+      if (!schema.$id) {
+        schema.$id = schemaData.path;
+      }
+      if (typeof schema.$id === 'string' && !schema.$id.startsWith('http://')) {
+        schema.$id = 'http://localhost/schemas/' + schema.$id;
+      }
+
+      // Remove existing schema if it exists to ensure reload
+      if (ajv.getSchema(schema.$id)) {
+        ajv.removeSchema(schema.$id);
+        logger.info(`Removed existing schema ${schema.$id} from AJV for reload.`);
+      }
+      try {
+        ajv.addSchema(schema, schema.$id);
+    
+      } catch (e) {
+        logger.error(`Error adding schema ${schema.$id} to AJV: ${e.message}`);
+      }
+
+    } catch (e) {
+      logger.error(`Error preloading schema ${schemaData.path}: ${e.message}`);
+    }
+  }
+}
+
+// Call preloadSchemas once at the module level
+preloadSchemas();
+
+/**
+ * Loads a schema by name (service or component) and version from the registry.
+ * This function handles recursive $ref resolution internally via AJV.
+ * @param {string} schemaName - The name of the schema (e.g., 'BirthChartService', 'astrology/vedic/input', 'v1/shared/PlatformContext').
+ * @param {string} [version='latest'] - The version of the service schema. Not applicable for components.
+ * @returns {object} The loaded and resolved JSON Schema object.
+ */
+function loadSchema(schemaName, version = 'latest') {
+  const cacheKey = `${schemaName}:${version}`;
+  // Try to get compiled validator from cache first
+  const cachedCompiledValidator = getCachedValidator(cacheKey);
+  if (cachedCompiledValidator) {
+    return cachedCompiledValidator.schema; // Return the raw schema object from the compiled validator
+  }
+
+  let finalSchemaId = null;
+
+    const registry = getRegistry();
+    let schemaPath = null;
+    const schemaNameParts = schemaName.split('/');
+
+    // Try to find the schema in services and components based on the hierarchical path
+    const searchInRegistrySection = (section) => {
+        let current = section;
+        let found = true;
+        const normalizedSchemaNameParts = schemaName.replace(/([A-Z])/g, '-$1').toLowerCase().split('/'); // Normalize
+        for (const part of normalizedSchemaNameParts) { // Use normalized parts
+            if (current && current[part]) {
+                current = current[part];
+            } else {
+                found = false;
+                break;
+            }
+        }
+        if (found && current) {
+            // Found the logical path, now determine the actual schema file path
+            let actualVersion = version;
+            if (version === 'latest' && current.latest) {
+                actualVersion = current.latest;
+            } else if (version === 'latest' && current.v1) { // Fallback to 'v1'
+                actualVersion = 'v1';
+            }
+
+            if (current[actualVersion] && current[actualVersion].path) {
+                return current[actualVersion].path;
+            } else if (current.path) { // For components that might not be versioned
+                return current.path;
+            }
+        }
+
+        return null;
+    };
+
+    // For non-hierarchical schema names (like 'platform-context'), look in shared
+    if (schemaNameParts.length === 1) {
+        const sharedSchema = registry.components.shared[schemaName];
+        if (sharedSchema && sharedSchema.path) {
+            schemaPath = sharedSchema.path;
+        }
+    } else {
+        schemaPath = searchInRegistrySection(registry.services);
+        if (!schemaPath) {
+            schemaPath = searchInRegistrySection(registry.components);
+        }
+    }
+
+    if (schemaPath) {
+        finalSchemaId = `http://localhost/schemas/${schemaPath}`;
+    } else if (schemaName.includes('/') && schemaName.endsWith('.json')) {
+        // Fallback: If schemaName looks like a direct file path and was not found in registry,
+        // assume it's a direct reference like 'v1/shared/error.v1.json'
+        finalSchemaId = `http://localhost/schemas/${schemaName}`;
+    }
+  
+    if (!finalSchemaId) {
+      throw new Error(`Schema '${schemaName}' not found in registry and cannot construct its absolute ID.`);
+    }
+  
+    // Retrieve the compiled validator from AJV. It should have been preloaded.
+    const compiledValidator = ajv.getSchema(finalSchemaId);
+  
+    if (!compiledValidator) {
+      throw new Error(`Schema '${finalSchemaId}' was not found in AJV instance. This indicates a problem with preloadSchemas or an unregistered schema.`);
+    }
+  
+    // Cache the compiled validator for future use
+    setCachedValidator(cacheKey, compiledValidator);
+    return compiledValidator.schema; // Return the raw schema object from the compiled validator
+}
+
+
+/**
+ * Collects all allowed property names from a schema, resolving allOf and $ref.
+ * @param {object} schema - The schema object
+ * @returns {Set<string>} Set of allowed property names
+ */
+function collectAllowedProperties(schema) {
+  const allowedProps = new Set();
+
+  // Helper function to process a single schema
+  function processSchema(subSchema) {
+    if (subSchema.properties) {
+      Object.keys(subSchema.properties).forEach(prop => allowedProps.add(prop));
+    }
+    if (subSchema.required) {
+      subSchema.required.forEach(prop => allowedProps.add(prop));
+    }
+
+    // Handle $ref
+    if (subSchema.$ref) {
+      const refSchema = ajv.getSchema(subSchema.$ref);
+      if (refSchema && refSchema.schema) {
+        processSchema(refSchema.schema);
+      }
+    }
+
+    // Handle allOf
+    if (subSchema.allOf) {
+      subSchema.allOf.forEach(sub => processSchema(sub));
+    }
+  }
+
+  processSchema(schema);
+  return allowedProps;
+}
+
+/**
+ * Validates input data against a specified schema.
+ * @param {string} schemaName - The name of the schema (service or component) to validate against.
+ * @param {object} input - The input data to validate.
+ * @param {string} [version='latest'] - The version of the schema.
+ * @returns {{isValid: boolean, errors?: object[], data?: object}} Validation result with processed data.
+ */
+function validateInput(schemaName, input, version = 'latest') {
+  try {
+    if (!input || typeof input !== 'object') {
+      return {
+        isValid: false,
+        errors: [{ message: 'Input must be a valid object' }],
+        data: input
+      };
+    }
+
+    const schema = loadSchema(schemaName, version);
+    const cacheKey = `${schemaName}:${version}`;
+    let validate = getCachedValidator(cacheKey);
+
+    if (!validate) {
+      validate = ajv.compile(schema);
+      setCachedValidator(cacheKey, validate);
+    }
+
+    // Create a fast deep copy to avoid modifying original input
+    const inputCopy = fastClone(input);
+
+    // AJV handles additional properties validation natively
+
+    // Additional strict checks
+    if (getStrictMode()) {
+      // Check for null/undefined values in required fields
+      if (schema.required) {
+        for (const requiredField of schema.required) {
+          if (inputCopy[requiredField] == null) {
+            return {
+              isValid: false,
+              errors: [{
+                field: `/${requiredField}`,
+                message: `Required property '${requiredField}' is null or undefined`,
+                keyword: 'required',
+                params: { missingProperty: requiredField }
+              }],
+              data: input
+            };
+          }
+        }
+      }
+
+      // Check for empty strings in string fields that shouldn't be empty
+      for (const [key, value] of Object.entries(inputCopy)) {
+        if (typeof value === 'string' && value.trim() === '' && schema.properties?.[key]?.type === 'string') {
+          return {
+            isValid: false,
+            errors: [{
+              field: `/${key}`,
+              message: `String property '${key}' cannot be empty`,
+              keyword: 'minLength',
+              params: { limit: 1 }
+            }],
+            data: input
+          };
+        }
+      }
+    }
+
+    // Validate with AJV
+    const isValid = validate(inputCopy);
+
+    return {
+      isValid,
+      errors: isValid ? null : validate.errors.map(err => ({
+        field: err.instancePath || '/',
+        message: err.message,
+        keyword: err.keyword,
+        params: err.params
+      })),
+      data: inputCopy // Return processed data with defaults applied
+    };
+  } catch (error) {
+    return {
+      isValid: false,
+      errors: [{ field: '/', message: `Schema validation setup error: ${error.message}` }],
+      data: input
+    };
+  }
+}
+
+/**
+ * Validates output data against a specified schema.
+ * More lenient than input validation - allows additional properties.
+ * @param {string} schemaName - The name of the schema to validate against.
+ * @param {object} output - The output data to validate.
+ * @param {string} [version='latest'] - The version of the schema.
+ * @returns {{isValid: boolean, errors?: object[]}} Validation result.
+ */
+function validateOutput(schemaName, output, version = 'latest') {
+  try {
+    if (!output || typeof output !== 'object') {
+      return {
+        isValid: false,
+        errors: [{ message: 'Output must be a valid object' }],
+        data: output
+      };
+    }
+
+    // Try to get the compiled validator from the main AJV instance
+    let validate = ajv.getSchema(schemaName);
+
+    if (!validate) {
+      // If not found, try loading and compiling the schema
+      const schema = loadSchema(schemaName, version);
+      const cacheKey = `${schemaName}:${version}:output`;
+
+      validate = getCachedValidator(cacheKey);
+
+      if (!validate) {
+        // Use the main AJV instance to compile (it has all schemas loaded)
+        try {
+          validate = ajv.compile(schema);
+          setCachedValidator(cacheKey, validate);
+        } catch (e) {
+          return {
+            isValid: false,
+            errors: [{ field: '/', message: `Schema compilation failed: ${e.message}` }],
+            data: output
+          };
+        }
+      }
+    }
+
+    // Create a fast deep copy to avoid modifying original output
+    const outputCopy = fastClone(output);
+
+    // Validate with strict AJV (rejects additional properties)
+    const isValid = validate(outputCopy);
+
+    return {
+      isValid,
+      errors: isValid ? null : validate.errors.map(err => ({
+        field: err.instancePath || '/',
+        message: err.message,
+        keyword: err.keyword,
+        params: err.params
+      })),
+      data: outputCopy // Return processed data with defaults applied
+    };
+  } catch (error) {
+    return {
+      isValid: false,
+      errors: [{ field: '/', message: `Schema validation setup error: ${error.message}` }],
+      data: output
+    };
+  }
+}
+
+/**
+ * Registers a new schema (service or component) in `schemaRegistry.json`.
+ * @param {string} schemaName - The name of the schema to register.
+ * @param {string} schemaPath - The path to the schema `.json` file, relative to `schemas/services` or `schemas/components` or `schemas/` itself.
+ * @param {string} [version='v1'] - The version of the schema (for services).
+ * @param {string} [type='service'] - 'service' or 'component' or 'top-level'.
+ * @param {boolean} [setAsLatest=true] - Whether to set this version as the latest for services.
+ */
+function registerSchema(schemaName, schemaPath, version = 'v1', type = 'service', setAsLatest = true) {
+  try {
+    const registryPath = path.join(__dirname, 'schemaRegistry.json');
+    const registry = getRegistry(); // Use getRegistry to ensure fresh data
+
+    if (type === 'service') {
+      if (!registry.services[schemaName]) {
+        registry.services[schemaName] = {};
+      }
+      registry.services[schemaName][version] = {
+        path: schemaPath,
+        status: 'active',
+        deprecated: false,
+        deprecationDate: null,
+        compatibility: []
+      };
+      if (setAsLatest) {
+        registry.services[schemaName].latest = version;
+      }
+    } else if (type === 'component') {
+      if (!registry.components[schemaName]) {
+        registry.components[schemaName] = {}; // Ensure components is an object
+      }
+      registry.components[schemaName] = {
+        path: schemaPath,
+        description: `Reusable component schema for '${schemaName}'`
+      };
+    } else if (type === 'top-level') { // For schemas like astrologyInputSchema.json
+        // For top-level schemas, path is directly in __dirname
+        registry.components[schemaName] = {
+            path: schemaPath,
+            description: `Top-level component schema for '${schemaName}'`
+        };
+    } else {
+      throw new Error(`Invalid schema type for registration: ${type}`);
+    }
+
+    registry.lastUpdated = new Date().toISOString().split('T')[0];
+    fs.writeFileSync(registryPath, JSON.stringify(registry, null, 2));
+
+    // Clear caches
+    schemaCache.clear();
+    validatorCache.clear();
+
+    logger.info(`Registered schema '${schemaName}' (type: ${type}, version: ${version}) at '${schemaPath}'.`);
+
+  } catch (error) {
+    throw new Error(`Failed to register schema '${schemaName}': ${error.message}`);
+  }
+}
+
+/**
+ * Clears all schema and validator caches.
+ */
+/**
+ * Clears all cached schemas and validators.
+ * Useful for development or when schemas are updated.
+ */
+function clearCache() {
+  schemaCache.clear();
+  validatorCache.clear();
+  schemaCacheTimestamps.clear();
+  validatorCacheTimestamps.clear();
+
+  // Remove all schemas from AJV to force reload
+  // Note: We can't easily enumerate all schemas in AJV, so we'll just reload
+  try {
+    // Try to remove the specific schema we know about
+    ajv.removeSchema('http://localhost/schemas/v1/domains/astrology/components/birthData.json');
+  } catch (error) {
+    // Ignore if schema doesn't exist
+  }
+
+  // Reload schemas into AJV
+  preloadSchemas();
+}
+
+/**
+ * Sets the strict validation mode.
+ * @param {boolean} enabled - Whether to enable strict validation
+ */
+function setStrictMode(enabled) {
+  // Note: This is a global setting that affects all validations
+  // In a production system, you might want per-request strictness
+  process.env.SCHEMA_STRICT_MODE = enabled.toString();
+}
+
+/**
+ * Gets the current strict validation mode.
+ * @returns {boolean} Whether strict mode is enabled
+ */
+function getStrictMode() {
+  return process.env.SCHEMA_STRICT_MODE !== 'false';
+}
+
+/**
+ * Validates a JSON Schema itself for correctness.
+ * @param {object} schema - The JSON Schema to validate.
+ * @returns {{isValid: boolean, errors?: string[]}} Schema validation result.
+ */
+function validateSchema(schema) {
+  try {
+    // Basic schema structure validation
+    if (!schema || typeof schema !== 'object') {
+      return { isValid: false, errors: ['Schema must be a valid object'] };
+    }
+
+    if (!schema.$schema && !schema.type) {
+      return { isValid: false, errors: ['Schema must have $schema or type property'] };
+    }
+
+    // Try to compile with AJV to check for structural issues
+    ajv.compile(schema);
+    return { isValid: true };
+  } catch (error) {
+    return { isValid: false, errors: [error.message] };
+  }
+}
+
+// Service-to-schema category mapping, storing registered service schema associations
+const serviceSchemaMap = new Map();
+
+// Register a service with its schema category
+const registerServiceSchema = (serviceName, schemaCategory) => {
+  serviceSchemaMap.set(serviceName, schemaCategory);
+};
+
+// Schema category to full schema name mapping
+const schemaCategoryToSchemaName = {
+  'vedic': 'v1/domains/astrology/inputs/vedic.v1.json',
+  'compatibility': 'v1/domains/astrology/inputs/compatibility.v1.json',
+  'location': 'v1/services/location/query.v1.json',
+  'ai': 'v1/services/ai/query.v1.json',
+  'database': 'v1/services/database/query.v1.json',
+  'logging': 'v1/services/logging/entry.v1.json',
+  'observability': 'v1/services/observability/query.v1.json',
+  'session': 'v1/domains/astrology/components/session-data.v1.json',
+  'default': 'v1/domains/astrology/inputs/vedic.v1.json'
+};
+
+// Service name to schema category mapping as fallback
+const serviceNameToSchemaCategory = {
+  'birthchart': 'vedic',
+  'dasha': 'vedic',
+  'ephemeris': 'vedic',
+  'astrologer': 'vedic',
+  'location': 'location',
+  'ai': 'ai',
+  'mongodb': 'database',
+  'logging': 'logging',
+  'observability': 'observability',
+  'sessionmanager': 'session'
+};
+
+// Create a service-specific validation function that maps service names to schemas
+const validateServiceInput = (serviceName, request) => {
+  // First check if service has a registered schema category
+  const registeredSchemaCategory = serviceSchemaMap.get(serviceName);
+  const schemaCategory = registeredSchemaCategory ||
+                         serviceNameToSchemaCategory[serviceName] ||
+                         'default';
+
+  const schemaName = schemaCategoryToSchemaName[schemaCategory] ||
+                     schemaCategoryToSchemaName['default'];
+
+  // Create a fast deep copy of the request to avoid modifying the original object during validation
+  // This prevents AJV from modifying the original request when applying defaults
+  const requestCopy = fastClone(request);
+
+  return validateInput(schemaName, requestCopy);
+};
+
+// Create service input schema getter function
+const getServiceInputSchema = (serviceName) => {
+  // First check if service has a registered schema category
+  const registeredSchemaCategory = serviceSchemaMap.get(serviceName);
+  const schemaCategory = registeredSchemaCategory ||
+                         serviceNameToSchemaCategory[serviceName] ||
+                         'default';
+
+  const schemaName = schemaCategoryToSchemaName[schemaCategory] ||
+                     schemaCategoryToSchemaName['default'];
+
+  return loadSchema(schemaName);
+};
+
+// Export the unified AJV schema management API
+module.exports = {
+  loadSchema,
+  validateInput,
+  validateOutput,
+  validateSchema, // New: Validate schema structure itself
+  registerSchema, // Renamed from registerServiceSchema for broader use
+  getRegistry,
+  clearCache,
+  setStrictMode, // New: Control strict validation mode
+  getStrictMode, // New: Check strict validation mode
+  validateServiceInput, // Added: Service-specific validation function
+  getServiceInputSchema, // Added: Service-specific schema getter
+  registerServiceSchema, // Added: Function to register service-to-schema mappings
+  // Enhanced schema registry functions
+  registerMethodSchemaMapping,
+  getMethodSchemaMapping,
+  getValidationSchemas,
+  registerSchemaVersion,
+  getSchemaVersion,
+  getSchemaVersionHistory,
+  clearSchemaCache: () => {
+    schemaCache.clear();
+    schemaCacheTimestamps.clear();
+  },
+};