@kravc/schema 2.8.0-alpha.6 → 2.8.0-alpha.8

package/src/helpers/normalizeRequired.ts

@@ -1,170 +1,10 @@
 import { isUndefined } from 'lodash';
 
-import type {
-  JsonSchema,
-  EnumSchema,
-  ObjectSchema,
-  ArrayPropertySchema,
-  ObjectPropertySchema,
-  ReferencePropertySchema,
-} from './JsonSchema';
-
 /**
  * Normalizes required field declarations in JSON schemas by converting property-level
  * `required` flags to schema-level `required` arrays and `x-required` metadata flags.
- *
- * **Intent:**
- * This function transforms JSON schemas from a property-centric required field model
- * (where each property has its own `required: true/false` flag) to the standard JSON Schema
- * format (where required fields are listed in a top-level `required` array). This normalization
- * ensures compatibility with JSON Schema validators while preserving the original required
- * field information through the `x-required` extension attribute.
- *
- * **Use Cases:**
- * 1. **Schema Standardization**: Convert custom schema formats to standard JSON Schema format
- *    for validator compatibility
- * 2. **Schema Transformation**: Prepare schemas for validation libraries that expect
- *    required fields in array format
- * 3. **Metadata Preservation**: Maintain required field information in both standard format
- *    (`required` array) and extension format (`x-required` flag) for different use cases
- * 4. **Schema Processing Pipeline**: Normalize schemas before validation, credential generation,
- *    or API documentation generation
- *
- * **Behavior:**
- * - Mutates the input schema in-place
- * - Moves `required: true` from property level to schema-level `required` array
- * - Sets `x-required: true` on properties that were marked as required
- * - Deletes the `required` property from individual property schemas
- * - Recursively processes nested object properties
- * - Recursively processes array items (including nested objects within arrays)
- * - Skips reference properties (`$ref`) as they are resolved elsewhere
- * - Skips EnumSchema (returns early)
- * - Only sets `required` array if at least one field is required
- *
- * **Examples:**
- *
- * ```typescript
- * // Example 1: Simple object schema
- * const schema = {
- *   id: 'User',
- *   properties: {
- *     name: { type: 'string', required: true },
- *     email: { type: 'string', required: true },
- *     age: { type: 'number', required: false }
- *   }
- * };
- *
- * normalizeRequired(schema);
- * // Result:
- * // schema.required = ['name', 'email']
- * // schema.properties.name['x-required'] = true
- * // schema.properties.email['x-required'] = true
- * // schema.properties.name.required = undefined (deleted)
- * // schema.properties.email.required = undefined (deleted)
- * ```
- *
- * ```typescript
- * // Example 2: Nested objects
- * const schema = {
- *   id: 'Order',
- *   properties: {
- *     user: {
- *       type: 'object',
- *       required: true,
- *       properties: {
- *         name: { type: 'string', required: true },
- *         address: {
- *           type: 'object',
- *           properties: {
- *             street: { type: 'string', required: true }
- *           }
- *         }
- *       }
- *     }
- *   }
- * };
- *
- * normalizeRequired(schema);
- * // Result:
- * // schema.required = ['user']
- * // schema.properties.user['x-required'] = true
- * // schema.properties.user.required = ['name']
- * // schema.properties.user.properties.name['x-required'] = true
- * // schema.properties.user.properties.address.required = ['street']
- * // schema.properties.user.properties.address.properties.street['x-required'] = true
- * ```
- *
- * ```typescript
- * // Example 3: Arrays with object items
- * const schema = {
- *   id: 'Order',
- *   properties: {
- *     items: {
- *       type: 'array',
- *       required: true,
- *       items: {
- *         type: 'object',
- *         properties: {
- *           productId: { type: 'string', required: true },
- *           quantity: { type: 'number', required: true }
- *         }
- *       }
- *     }
- *   }
- * };
- *
- * normalizeRequired(schema);
- * // Result:
- * // schema.required = ['items']
- * // schema.properties.items['x-required'] = true
- * // schema.properties.items.items.required = ['productId', 'quantity']
- * // schema.properties.items.items.properties.productId['x-required'] = true
- * // schema.properties.items.items.properties.quantity['x-required'] = true
- * ```
- *
- * ```typescript
- * // Example 4: Mixed structure
- * const schema = {
- *   id: 'Profile',
- *   properties: {
- *     name: { type: 'string', required: true },
- *     address: {
- *       type: 'object',
- *       required: true,
- *       properties: {
- *         street: { type: 'string', required: true },
- *         city: { type: 'string' }
- *       }
- *     },
- *     tags: {
- *       type: 'array',
- *       items: {
- *         type: 'object',
- *         properties: {
- *           label: { type: 'string', required: true }
- *         }
- *       }
- *     }
- *   }
- * };
- *
- * normalizeRequired(schema);
- * // Result:
- * // schema.required = ['name', 'address']
- * // All nested required fields are normalized recursively
- * ```
- *
- * **Limitations:**
- * - Only processes schemas with a `properties` field (ObjectSchema or ObjectPropertySchema)
- * - EnumSchema is accepted but returns early without processing
- * - Reference properties (`$ref`) are skipped and not processed
- * - The function mutates the input schema object
- * - Does not resolve `$ref` references (they must be resolved separately)
- *
- * @param jsonSchema - The JSON schema to normalize (ObjectSchema, ObjectPropertySchema, or ReferencePropertySchema)
- * @returns void (mutates the input schema in-place)
  */
-const normalizeRequired = (jsonSchema: JsonSchema | ObjectPropertySchema | ReferencePropertySchema) => {
+const normalizeRequired = (jsonSchema: EnumSchema | ObjectSchema | ObjectPropertySchema | ReferencePropertySchema) => {
   const { enum: enumItems } = (jsonSchema as EnumSchema);
 
   const isEnum = !!enumItems;

package/src/helpers/normalizeType.ts

@@ -3,169 +3,41 @@ type ValueType = 'number' | 'integer' | 'boolean' | 'string' | 'object' | 'array
 const BOOLEAN_STRING_TRUE_VALUES = ['yes', 'true', '1'];
 const BOOLEAN_STRING_FALSE_VALUES = ['no', 'false', '0'];
 
-/**
- * Checks if a value is null or undefined.
- *
- * @param value - The value to check
- * @returns True if the value is null or undefined, false otherwise
- */
+/** Checks if a value is null or undefined. */
 const isNullOrUndefined = (value: unknown): value is null | undefined =>
   value === null || value === undefined;
 
-/**
- * Checks if a JSON Schema type is numeric (number or integer).
- *
- * @param type - The JSON Schema type to check
- * @returns True if the type is 'number' or 'integer', false otherwise
- */
+/** Checks if a JSON Schema type is numeric (number or integer). */
 const isNumericType = (type: ValueType): boolean => type === 'number' || type === 'integer';
 
-/**
- * Checks if a JSON Schema type is boolean.
- *
- * @param type - The JSON Schema type to check
- * @returns True if the type is 'boolean', false otherwise
- */
+/** Checks if a JSON Schema type is boolean. */
 const isBooleanType = (type: ValueType): boolean => type === 'boolean';
 
-/**
- * Type guard that checks if a value is a number.
- *
- * @param value - The value to check
- * @returns True if the value is a number, false otherwise
- */
+/** Type guard that checks if a value is a number. */
 const isNumberValue = (value: unknown): value is number => typeof value === 'number';
 
-/**
- * Type guard that checks if a value is a boolean.
- *
- * @param value - The value to check
- * @returns True if the value is a boolean, false otherwise
- */
+/** Type guard that checks if a value is a boolean. */
 const isBooleanValue = (value: unknown): value is boolean => typeof value === 'boolean';
 
-/**
- * Type guard that checks if a value is a string.
- *
- * @param value - The value to check
- * @returns True if the value is a string, false otherwise
- */
+/** Type guard that checks if a value is a string. */
 const isStringValue = (value: unknown): value is string => typeof value === 'string';
 
-/**
- * Checks if a string is empty or contains only whitespace characters.
- *
- * @param value - The string to check
- * @returns True if the string is empty or whitespace-only, false otherwise
- */
+/** Checks if a string is empty or contains only whitespace characters. */
 const isEmptyOrWhitespaceString = (value: string): boolean =>
   value === '' || value.trim() === '';
 
-/**
- * Checks if a number is valid (not NaN).
- *
- * @param value - The number to check
- * @returns True if the number is valid (not NaN), false otherwise
- */
+/** Checks if a number is valid (not NaN). */
 const isValidNumber = (value: number): boolean => !isNaN(value);
 
-/**
- * Checks if a string represents a boolean true value.
- * Recognized values (case-insensitive): 'yes', 'true', '1'.
- *
- * @param value - The string to check
- * @returns True if the string represents a boolean true value, false otherwise
- */
+/** Checks if a string represents a boolean true value. */
 const isBooleanTrueString = (value: string): boolean =>
   BOOLEAN_STRING_TRUE_VALUES.includes(value.toLowerCase());
 
-/**
- * Checks if a string represents a boolean false value.
- * Recognized values (case-insensitive): 'no', 'false', '0'.
- *
- * @param value - The string to check
- * @returns True if the string represents a boolean false value, false otherwise
- */
+/** Checks if a string represents a boolean false value. */
 const isBooleanFalseString = (value: string): boolean =>
   BOOLEAN_STRING_FALSE_VALUES.includes(value.toLowerCase());
 
-/**
- * Normalizes a value to match a specified JSON Schema type.
- *
- * ## Intent
- *
- * This function is designed to coerce values into their expected types based on JSON Schema
- * type definitions. It's particularly useful when processing data from external sources (like
- * form inputs, query parameters, or API responses) where values may arrive as strings but
- * need to be converted to their proper types according to a schema definition.
- *
- * The function performs type coercion where appropriate, but preserves the original value
- * when conversion is not possible or when the value is already of the correct type. This
- * makes it safe to use in data normalization pipelines without losing information.
- *
- * ## Use Cases
- *
- * 1. **Schema-based data normalization**: When processing objects against JSON Schema
- *    definitions, ensuring property values match their declared types.
- *
- * 2. **Form data processing**: Converting string values from HTML forms (which are always
- *    strings) to their expected types (numbers, booleans) based on schema definitions.
- *
- * 3. **API response normalization**: Normalizing API responses where types may be ambiguous
- *    or incorrectly serialized (e.g., numbers as strings, booleans as strings).
- *
- * 4. **Configuration parsing**: Parsing configuration values from environment variables or
- *    config files where everything is initially a string but needs type coercion.
- *
- * ## Behavior by Type
- *
- * - **number/integer**: Attempts to convert strings and booleans to numbers. Preserves
- *   original value if conversion fails or value is already a number.
- *
- * - **boolean**: Converts numbers (0 → false, non-zero → true) and recognized string
- *   values ('yes', 'true', '1' → true; 'no', 'false', '0' → false). Preserves original
- *   value for unrecognized strings or non-convertible types.
- *
- * - **string/object/array**: Returns the value as-is (no conversion performed).
- *
- * - **null/undefined**: Always preserved regardless of target type.
- *
- * ## Examples
- *
- * ### Number Conversion
- * ```typescript
- * normalizeType('number', '123')      // → 123
- * normalizeType('number', '45.67')    // → 45.67
- * normalizeType('number', '0')        // → 0
- * normalizeType('number', true)       // → 1
- * normalizeType('number', 'abc')      // → 'abc' (conversion failed, original preserved)
- * ```
- *
- * ### Boolean Conversion
- * ```typescript
- * normalizeType('boolean', 0)         // → false
- * normalizeType('boolean', 1)         // → true
- * normalizeType('boolean', 'yes')     // → true
- * normalizeType('boolean', 'true')    // → true
- * normalizeType('boolean', '1')       // → true
- * normalizeType('boolean', 'no')      // → false
- * normalizeType('boolean', 'false')   // → false
- * normalizeType('boolean', 'maybe')   // → 'maybe' (unrecognized, original preserved)
- * ```
- *
- * ### Type Preservation
- * ```typescript
- * normalizeType('string', 'hello')    // → 'hello'
- * normalizeType('string', 123)        // → 123 (no conversion for string type)
- * normalizeType('object', { a: 1 })   // → { a: 1 }
- * normalizeType('array', [1, 2, 3])   // → [1, 2, 3]
- * normalizeType('number', null)       // → null (null always preserved)
- * ```
- *
- * @param type - The target JSON Schema type ('number', 'integer', 'boolean', 'string', 'object', 'array')
- * @param value - The value to normalize (can be any type)
- * @returns The normalized value, or the original value if normalization is not applicable
- */
+/** Normalizes a value to match a specified JSON Schema type. */
 const normalizeType = (type: ValueType, value: unknown): string | number | boolean | unknown => {
   // Preserve null and undefined values regardless of target type
   if (isNullOrUndefined(value)) {

package/src/helpers/nullifyEmptyValues.ts

@@ -1,7 +1,5 @@
 import { get, set } from 'lodash';
-import { schemaSymbol, jsonSymbol, type SchemaErrorDetail } from 'z-schema';
-
-import type { TargetObject } from './JsonSchema';
+import ZSchema, { type SchemaErrorDetail } from 'z-schema';
 
 /**
  * Format error codes that indicate validation failures due to format mismatches.
@@ -13,145 +11,10 @@ const FORMAT_ERROR_CODES = [
   'INVALID_FORMAT'
 ] as const;
 
-/**
- * Values that are considered "empty" and can be safely converted to null.
- */
+/** Values that are considered "empty" and can be safely converted to null. */
 const EMPTY_VALUES = [''] as const;
 
-/**
- * Converts empty string values to null for specific format validation errors.
- * 
- * **Intent:**
- * This function provides a post-validation normalization strategy that attempts to
- * resolve format validation errors by converting empty strings to null. This is
- * particularly useful when dealing with optional fields where an empty string
- * represents "no value provided" rather than an invalid format. By converting
- * empty strings to null, the validation may pass if the schema allows null values
- * for optional fields.
- * 
- * **Use Cases:**
- * - **Optional field normalization**: When optional string fields receive empty
- *   strings from user input or API responses, converting them to null allows
- *   validation to succeed if the schema permits null values for optional fields.
- *   This is especially common with form inputs that submit empty strings instead
- *   of omitting fields entirely.
- * - **Format error recovery**: After schema validation fails with format errors
- *   (pattern mismatch, enum mismatch, invalid format), this function attempts to
- *   resolve errors by nullifying empty strings. This enables graceful handling
- *   of optional fields that failed format validation due to empty values.
- * - **API integration**: When integrating with external APIs or services that
- *   send empty strings for optional fields, this function normalizes the data
- *   to use null instead, which is often more semantically correct for optional
- *   fields in JSON schemas.
- * - **Data transformation pipeline**: As part of a validation and normalization
- *   pipeline, this function can be used to clean and normalize data before
- *   further processing or storage, ensuring consistent representation of
- *   "missing" values.
- * - **User input handling**: When processing user-submitted forms or data where
- *   empty string inputs should be treated as "not provided" rather than invalid,
- *   this function converts them to null for proper schema validation.
- * 
- * **Behavior:**
- * - Returns a deep clone of the input object (does not mutate the original)
- * - Only processes format-related errors (PATTERN, ENUM_MISMATCH, INVALID_FORMAT)
- * - Skips required attributes (marked with `x-required: true`)
- * - Only converts empty strings (`''`) to null, preserving other values
- * - Supports nested paths and array indices
- * - Returns both the modified object and remaining validation errors that
- *   couldn't be resolved
- * 
- * **Examples:**
- * 
- * ```typescript
- * // Example 1: Basic usage with pattern error
- * const object = { email: '' };
- * const error = {
- *   code: 'PATTERN',
- *   path: '#/email',
- *   // ... other error properties
- * };
- * const [result, remainingErrors] = nullifyEmptyValues(object, [error]);
- * // result: { email: null }
- * // remainingErrors: []
- * ```
- * 
- * ```typescript
- * // Example 2: Required fields are not nullified
- * const object = { requiredField: '', optionalField: '' };
- * const requiredError = {
- *   code: 'PATTERN',
- *   path: '#/requiredField',
- *   // schema has x-required: true
- * };
- * const optionalError = {
- *   code: 'PATTERN',
- *   path: '#/optionalField',
- *   // schema has no x-required or x-required: false
- * };
- * const [result, remainingErrors] = nullifyEmptyValues(
- *   object,
- *   [requiredError, optionalError]
- * );
- * // result: { requiredField: '', optionalField: null }
- * // remainingErrors: [requiredError] // required field error remains
- * ```
- * 
- * ```typescript
- * // Example 3: Nested paths and arrays
- * const object = {
- *   user: {
- *     profile: {
- *       bio: '',
- *       tags: ['', 'tag1', '']
- *     }
- *   }
- * };
- * const errors = [
- *   { code: 'PATTERN', path: '#/user/profile/bio' },
- *   { code: 'INVALID_FORMAT', path: '#/user/profile/tags/0' },
- *   { code: 'ENUM_MISMATCH', path: '#/user/profile/tags/2' }
- * ];
- * const [result, remainingErrors] = nullifyEmptyValues(object, errors);
- * // result: {
- * //   user: {
- * //     profile: {
- * //       bio: null,
- * //       tags: [null, 'tag1', null]
- * //     }
- * //   }
- * // }
- * // remainingErrors: []
- * ```
- * 
- * ```typescript
- * // Example 4: Non-format errors are not processed
- * const object = { field: '' };
- * const formatError = { code: 'PATTERN', path: '#/field' };
- * const typeError = { code: 'INVALID_TYPE', path: '#/field' };
- * const [result, remainingErrors] = nullifyEmptyValues(
- *   object,
- *   [formatError, typeError]
- * );
- * // result: { field: null }
- * // remainingErrors: [typeError] // type error remains
- * ```
- * 
- * ```typescript
- * // Example 5: Non-empty values are preserved
- * const object = { field: 'invalid-value' };
- * const error = { code: 'PATTERN', path: '#/field' };
- * const [result, remainingErrors] = nullifyEmptyValues(object, [error]);
- * // result: { field: 'invalid-value' } // unchanged
- * // remainingErrors: [error] // error remains
- * ```
- * 
- * @param object - The target object to process (will be deep cloned, not mutated)
- * @param validationErrors - Array of schema validation errors from z-schema
- * @returns A tuple containing:
- *   - `[0]`: Deep clone of the object with empty strings converted to null where applicable
- *   - `[1]`: Array of validation errors that couldn't be resolved (required fields,
- *            non-format errors, or errors for non-empty values)
- */
+/** Converts empty string values to null for specific format validation errors. */
 const nullifyEmptyValues = (
   object: TargetObject,
   validationErrors: SchemaErrorDetail[]
@@ -162,7 +25,7 @@ const nullifyEmptyValues = (
 
   for (const error of validationErrors) {
     const { code, path: pathString } = error;
-    const schema = get(error, schemaSymbol) as Record<string, unknown> | undefined;
+    const schema = get(error, ZSchema.schemaSymbol) as Record<string, unknown> | undefined;
     const isAttributeRequired = schema?.['x-required'] === true;
     const isFormatError = FORMAT_ERROR_CODES.includes(code as typeof FORMAT_ERROR_CODES[number]);
 
@@ -182,11 +45,13 @@ const nullifyEmptyValues = (
     }
 
     // Parse the JSON path (e.g., '#/user/profile/field' -> ['user', 'profile', 'field'])
-    const path = pathString.replace(/^#\//, '').split('/').filter(Boolean);
+    const path = typeof pathString === 'string'
+      ? pathString.replace(/^#\//, '').split('/').filter(Boolean)
+      : pathString;
 
-    // Get the actual value from the error's JSON context
-    const json = get(error, jsonSymbol) as TargetObject;
-    const value = get(json, path);
+    // Get the actual value from the error's JSON context, or fall back to the object
+    const json = get(error, ZSchema.jsonSymbol) as TargetObject | undefined;
+    const value = get(json ?? result, path);
 
     const isEmptyValue = EMPTY_VALUES.includes(value as typeof EMPTY_VALUES[number]);
     const shouldSkipNonEmptyValue = !isEmptyValue;

package/src/helpers/removeRequiredAndDefault.ts

@@ -1,110 +1,5 @@
-import type {
-  EnumSchema,
-  PropertySchema,
-  ArrayPropertySchema,
-  ObjectPropertySchema,
-} from './JsonSchema';
 
-/**
- * Recursively removes `required` and `default` attributes from a JSON schema.
- *
- * **Intent:**
- * This function is designed to transform JSON schemas by stripping out validation
- * constraints (`required`) and default values (`default`) from all properties,
- * including nested objects and array items. This is useful for creating "pure"
- * or "update-friendly" versions of schemas where all fields become optional and
- * no defaults are applied.
- *
- * **Use Cases:**
- * 1. **Update Schemas**: Create schemas for partial updates where all fields are optional
- * 2. **Schema Transformation**: Prepare schemas for contexts where required/default
- *    constraints are not needed (e.g., credential generation, API transformations)
- * 3. **Schema Normalization**: Remove validation metadata before further processing
- *
- * **Behavior:**
- * - Mutates the input schema in-place by deleting `required` and `default` properties
- * - Recursively processes nested object properties
- * - Recursively processes array items (including nested objects within arrays)
- * - Preserves all other schema properties (type, description, pattern, etc.)
- * - Returns an object containing only the `properties` field
- *
- * **Examples:**
- *
- * ```typescript
- * // Example 1: Simple object schema
- * const schema = {
- *   type: 'object',
- *   properties: {
- *     name: { type: 'string', required: true, default: 'John' },
- *     age: { type: 'number', required: false, default: 0 }
- *   }
- * };
- *
- * const result = removeRequiredAndDefault(schema);
- * // result.properties.name: { type: 'string' } (required and default removed)
- * // result.properties.age: { type: 'number' } (required and default removed)
- * ```
- *
- * ```typescript
- * // Example 2: Nested objects
- * const schema = {
- *   type: 'object',
- *   properties: {
- *     user: {
- *       type: 'object',
- *       required: true,
- *       default: {},
- *       properties: {
- *         name: { type: 'string', required: true, default: 'John' },
- *         address: {
- *           type: 'object',
- *           properties: {
- *             street: { type: 'string', required: true, default: '' }
- *           }
- *         }
- *       }
- *     }
- *   }
- * };
- *
- * const result = removeRequiredAndDefault(schema);
- * // All required and default attributes are removed at all nesting levels
- * ```
- *
- * ```typescript
- * // Example 3: Arrays with object items
- * const schema = {
- *   type: 'object',
- *   properties: {
- *     users: {
- *       type: 'array',
- *       required: true,
- *       default: [],
- *       items: {
- *         type: 'object',
- *         properties: {
- *           name: { type: 'string', required: true, default: 'John' }
- *         }
- *       }
- *     }
- *   }
- * };
- *
- * const result = removeRequiredAndDefault(schema);
- * // Removes required/default from array property and nested object properties
- * ```
- *
- * **Limitations:**
- * - Only processes schemas with a `properties` field (ObjectPropertySchema)
- * - EnumSchema is accepted as a parameter but not processed (will return empty properties)
- * - The function mutates the input schema object
- * - Array items that are primitives (string, number, etc.) are processed but
- *   their return values are discarded (this is intentional)
- *
- * @param jsonSchema - The JSON schema to process (must have a `properties` field)
- * @returns An object containing only the `properties` field with all `required`
- *          and `default` attributes removed recursively
- */
+/** Recursively removes `required` and `default` attributes from a JSON schema. */
 const removeRequiredAndDefault = (jsonSchema: PropertySchema | EnumSchema) => {
   const { properties } = (jsonSchema as ObjectPropertySchema);
 

package/src/helpers/validateId.ts

@@ -1,41 +1,6 @@
 import { isURL } from 'validator';
 
-/**
- * Validates that a value is a URL or a DID (Decentralized Identifier).
- * Throws if the value is missing, null, undefined, or not a valid URL/DID.
- *
- * **Intent**
- * Enforce that identifier-style parameters (schema IDs, credential IDs, subject
- * references, etc.) are either resolvable URLs or W3C DIDs before they are used
- * in Linked Data or verification flows. This prevents malformed or arbitrary
- * strings from propagating into storage, APIs, or cryptographic operations.
- *
- * **Use cases**
- * - Validating `schemaId`, `credentialId`, or similar parameters in credential
- *   and schema factories before creating or resolving documents.
- * - Input validation for APIs that accept URI identifiers (e.g. fetch by ID).
- * - Guarding helpers that resolve or dereference IDs (e.g. document loaders,
- *   schema registries) from invalid input.
- *
- * **Examples**
- *
- * Valid — URLs:
- *   validateId('schemaId', 'https://example.com/schemas/v1');
- *   validateId('id', 'http://example.com:8080/path?q=1');
- *
- * Valid — DIDs (case-insensitive `did:` prefix):
- *   validateId('subject', 'did:example:123456789');
- *   validateId('subject', 'did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK');
- *
- * Throws — missing or invalid:
- *   validateId('id', '');        // Error: Parameter "id" is required
- *   validateId('id', null);      // Error: Parameter "id" is required
- *   validateId('id', 'not-a-uri'); // Error: Parameter "id" must be a URL, received: "not-a-uri"
- *
- * @param name - Parameter name used in error messages (e.g. `"schemaId"`, `"credentialId"`).
- * @param value - The value to validate (`string`, `null`, or `undefined`).
- * @throws {Error} When `value` is falsy, or when it is not a URL and does not start with `did:`.
- */
+/** Validates that a value is a URL or a DID (Decentralized Identifier). */
 const validateId = (name: string, value: string | null | undefined) => {
   if (!value) {
     throw new Error(`Parameter "${name}" is required`);