@kravc/schema 2.7.5 → 2.8.0-alpha.0

package/dist/helpers/nullifyEmptyValues.d.ts

@@ -0,0 +1,139 @@
+import { type SchemaErrorDetail } from 'z-schema';
+import type { TargetObject } from './JsonSchema';
+/**
+ * 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)
+ */
+declare const nullifyEmptyValues: (object: TargetObject, validationErrors: SchemaErrorDetail[]) => [TargetObject, SchemaErrorDetail[]];
+export default nullifyEmptyValues;
+//# sourceMappingURL=nullifyEmptyValues.d.ts.map

package/dist/helpers/nullifyEmptyValues.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nullifyEmptyValues.d.ts","sourceRoot":"","sources":["../../src/helpers/nullifyEmptyValues.ts"],"names":[],"mappings":"AACA,OAAO,EAA4B,KAAK,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAE5E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAiBjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqIG;AACH,QAAA,MAAM,kBAAkB,GACtB,QAAQ,YAAY,EACpB,kBAAkB,iBAAiB,EAAE,KACpC,CAAC,YAAY,EAAE,iBAAiB,EAAE,CA+CpC,CAAC;AAEF,eAAe,kBAAkB,CAAC"}

package/dist/helpers/nullifyEmptyValues.js

@@ -0,0 +1,191 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const lodash_1 = require("lodash");
+const z_schema_1 = require("z-schema");
+/**
+ * Format error codes that indicate validation failures due to format mismatches.
+ * These errors can potentially be resolved by converting empty strings to null.
+ */
+const FORMAT_ERROR_CODES = [
+    'PATTERN',
+    'ENUM_MISMATCH',
+    'INVALID_FORMAT'
+];
+/**
+ * Values that are considered "empty" and can be safely converted to null.
+ */
+const EMPTY_VALUES = [''];
+/**
+ * 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)
+ */
+const nullifyEmptyValues = (object, validationErrors) => {
+    // Create a deep clone to avoid mutating the original object
+    const result = JSON.parse(JSON.stringify(object));
+    const remainingErrors = [];
+    for (const error of validationErrors) {
+        const { code, path: pathString } = error;
+        const schema = (0, lodash_1.get)(error, z_schema_1.schemaSymbol);
+        const isAttributeRequired = schema?.['x-required'] === true;
+        const isFormatError = FORMAT_ERROR_CODES.includes(code);
+        const shouldSkipRequiredAttribute = isAttributeRequired;
+        const shouldSkipNonFormatError = !isFormatError;
+        // Skip required attributes - they should not be nullified
+        if (shouldSkipRequiredAttribute) {
+            remainingErrors.push(error);
+            continue;
+        }
+        // Only process format-related errors
+        if (shouldSkipNonFormatError) {
+            remainingErrors.push(error);
+            continue;
+        }
+        // Parse the JSON path (e.g., '#/user/profile/field' -> ['user', 'profile', 'field'])
+        const path = pathString.replace(/^#\//, '').split('/').filter(Boolean);
+        // Get the actual value from the error's JSON context
+        const json = (0, lodash_1.get)(error, z_schema_1.jsonSymbol);
+        const value = (0, lodash_1.get)(json, path);
+        const isEmptyValue = EMPTY_VALUES.includes(value);
+        const shouldSkipNonEmptyValue = !isEmptyValue;
+        // Only nullify if the value is actually empty
+        if (shouldSkipNonEmptyValue) {
+            remainingErrors.push(error);
+            continue;
+        }
+        // Set the value to null in the result object
+        (0, lodash_1.set)(result, path, null);
+    }
+    return [result, remainingErrors];
+};
+exports.default = nullifyEmptyValues;
+//# sourceMappingURL=nullifyEmptyValues.js.map

package/dist/helpers/nullifyEmptyValues.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nullifyEmptyValues.js","sourceRoot":"","sources":["../../src/helpers/nullifyEmptyValues.ts"],"names":[],"mappings":";;AAAA,mCAAkC;AAClC,uCAA4E;AAI5E;;;GAGG;AACH,MAAM,kBAAkB,GAAG;IACzB,SAAS;IACT,eAAe;IACf,gBAAgB;CACR,CAAC;AAEX;;GAEG;AACH,MAAM,YAAY,GAAG,CAAC,EAAE,CAAU,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqIG;AACH,MAAM,kBAAkB,GAAG,CACzB,MAAoB,EACpB,gBAAqC,EACA,EAAE;IACvC,4DAA4D;IAC5D,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAiB,CAAC;IAClE,MAAM,eAAe,GAAwB,EAAE,CAAC;IAEhD,KAAK,MAAM,KAAK,IAAI,gBAAgB,EAAE,CAAC;QACrC,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,KAAK,CAAC;QACzC,MAAM,MAAM,GAAG,IAAA,YAAG,EAAC,KAAK,EAAE,uBAAY,CAAwC,CAAC;QAC/E,MAAM,mBAAmB,GAAG,MAAM,EAAE,CAAC,YAAY,CAAC,KAAK,IAAI,CAAC;QAC5D,MAAM,aAAa,GAAG,kBAAkB,CAAC,QAAQ,CAAC,IAAyC,CAAC,CAAC;QAE7F,MAAM,2BAA2B,GAAG,mBAAmB,CAAC;QACxD,MAAM,wBAAwB,GAAG,CAAC,aAAa,CAAC;QAEhD,0DAA0D;QAC1D,IAAI,2BAA2B,EAAE,CAAC;YAChC,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAC5B,SAAS;QACX,CAAC;QAED,qCAAqC;QACrC,IAAI,wBAAwB,EAAE,CAAC;YAC7B,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAC5B,SAAS;QACX,CAAC;QAED,qFAAqF;QACrF,MAAM,IAAI,GAAG,UAAU,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAEvE,qDAAqD;QACrD,MAAM,IAAI,GAAG,IAAA,YAAG,EAAC,KAAK,EAAE,qBAAU,CAAiB,CAAC;QACpD,MAAM,KAAK,GAAG,IAAA,YAAG,EAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAE9B,MAAM,YAAY,GAAG,YAAY,CAAC,QAAQ,CAAC,KAAoC,CAAC,CAAC;QACjF,MAAM,uBAAuB,GAAG,CAAC,YAAY,CAAC;QAE9C,8CAA8C;QAC9C,IAAI,uBAAuB,EAAE,CAAC;YAC5B,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAC5B,SAAS;QACX,CAAC;QAED,6CAA6C;QAC7C,IAAA,YAAG,EAAC,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IAC1B,CAAC;IAED,OAAO,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;AACnC,CAAC,CAAC;AAEF,kBAAe,kBAAkB,CAAC"}

package/dist/helpers/removeRequiredAndDefault.d.ts

@@ -0,0 +1,106 @@
+import type { EnumSchema, PropertySchema } 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
+ */
+declare const removeRequiredAndDefault: (jsonSchema: PropertySchema | EnumSchema) => {
+    properties: import("./JsonSchema").PropertiesSchema;
+};
+export default removeRequiredAndDefault;
+//# sourceMappingURL=removeRequiredAndDefault.d.ts.map

package/dist/helpers/removeRequiredAndDefault.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"removeRequiredAndDefault.d.ts","sourceRoot":"","sources":["../../src/helpers/removeRequiredAndDefault.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EACV,cAAc,EAGf,MAAM,cAAc,CAAC;AAEtB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmGG;AACH,QAAA,MAAM,wBAAwB,GAAI,YAAY,cAAc,GAAG,UAAU;;CAyCxE,CAAC;AAEF,eAAe,wBAAwB,CAAC"}

package/dist/helpers/removeRequiredAndDefault.js

@@ -0,0 +1,138 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * 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
+ */
+const removeRequiredAndDefault = (jsonSchema) => {
+    const { properties } = jsonSchema;
+    if (!properties) {
+        return { properties: {} };
+    }
+    for (const fieldName in properties) {
+        const property = properties[fieldName];
+        // Remove required and default from the property itself
+        delete property.required;
+        delete property.default;
+        // Check if property has a type to determine how to process it
+        const { type } = property;
+        const isObject = type === 'object';
+        const isArray = type === 'array';
+        if (isObject) {
+            // Recursively process nested object properties
+            removeRequiredAndDefault(property);
+            continue;
+        }
+        if (isArray) {
+            const { items } = property;
+            if (items) {
+                // Recursively process array items
+                // Note: For EnumSchema/ReferencePropertySchema items without properties,
+                // this will return { properties: {} } but the items themselves are not
+                // modified (only properties within objects are processed)
+                removeRequiredAndDefault(items);
+            }
+        }
+        // For other types (string, number, boolean, etc.) or properties without type,
+        // no further processing is needed
+    }
+    return { properties };
+};
+exports.default = removeRequiredAndDefault;
+//# sourceMappingURL=removeRequiredAndDefault.js.map

package/dist/helpers/removeRequiredAndDefault.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"removeRequiredAndDefault.js","sourceRoot":"","sources":["../../src/helpers/removeRequiredAndDefault.ts"],"names":[],"mappings":";;AAOA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmGG;AACH,MAAM,wBAAwB,GAAG,CAAC,UAAuC,EAAE,EAAE;IAC3E,MAAM,EAAE,UAAU,EAAE,GAAI,UAAmC,CAAC;IAE5D,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,OAAO,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC;IAC5B,CAAC;IAED,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,MAAM,QAAQ,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC;QAEvC,uDAAuD;QACvD,OAAO,QAAQ,CAAC,QAAQ,CAAC;QACzB,OAAO,QAAQ,CAAC,OAAO,CAAC;QAExB,8DAA8D;QAC9D,MAAM,EAAE,IAAI,EAAE,GAAI,QAAuD,CAAC;QAE1E,MAAM,QAAQ,GAAG,IAAI,KAAK,QAAQ,CAAC;QACnC,MAAM,OAAO,GAAG,IAAI,KAAK,OAAO,CAAC;QAEjC,IAAI,QAAQ,EAAE,CAAC;YACb,+CAA+C;YAC/C,wBAAwB,CAAC,QAAgC,CAAC,CAAC;YAC3D,SAAS;QACX,CAAC;QAED,IAAI,OAAO,EAAE,CAAC;YACZ,MAAM,EAAE,KAAK,EAAE,GAAI,QAAgC,CAAC;YACpD,IAAI,KAAK,EAAE,CAAC;gBACV,kCAAkC;gBAClC,yEAAyE;gBACzE,uEAAuE;gBACvE,0DAA0D;gBAC1D,wBAAwB,CAAC,KAAK,CAAC,CAAC;YAClC,CAAC;QACH,CAAC;QACD,8EAA8E;QAC9E,kCAAkC;IACpC,CAAC;IAED,OAAO,EAAE,UAAU,EAAE,CAAC;AACxB,CAAC,CAAC;AAEF,kBAAe,wBAAwB,CAAC"}

package/dist/helpers/validateId.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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:`.
+ */
+declare const validateId: (name: string, value: string | null | undefined) => void;
+export default validateId;
+//# sourceMappingURL=validateId.d.ts.map

package/dist/helpers/validateId.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateId.d.ts","sourceRoot":"","sources":["../../src/helpers/validateId.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,QAAA,MAAM,UAAU,GAAI,MAAM,MAAM,EAAE,OAAO,MAAM,GAAG,IAAI,GAAG,SAAS,SAYjE,CAAC;AAEF,eAAe,UAAU,CAAC"}