@kravc/schema 2.7.6 → 2.8.0-alpha.0

package/src/helpers/normalizeType.ts

@@ -0,0 +1,235 @@
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+const normalizeType = (type: ValueType, value: unknown): string | number | boolean | unknown => {
+  // Preserve null and undefined values regardless of target type
+  if (isNullOrUndefined(value)) {
+    return value;
+  }
+
+  // Handle number and integer types
+  if (isNumericType(type)) {
+    // If already a number, return as-is
+    if (isNumberValue(value)) {
+      return value;
+    }
+
+    // Convert booleans to numbers: true → 1, false → 0
+    if (isBooleanValue(value)) {
+      return value ? 1 : 0;
+    }
+
+    // Attempt conversion for strings
+    if (isStringValue(value)) {
+      // Preserve empty strings and whitespace-only strings
+      if (isEmptyOrWhitespaceString(value)) {
+        return value;
+      }
+
+      const converted = Number(value);
+      // Check if conversion was successful (not NaN)
+      if (isValidNumber(converted)) {
+        return converted;
+      }
+    }
+
+    // Return original value if conversion failed or type is not convertible
+    return value;
+  }
+
+  // Handle boolean type
+  if (isBooleanType(type)) {
+    // If already a boolean, return as-is
+    if (isBooleanValue(value)) {
+      return value;
+    }
+
+    // Convert numbers: 0 → false, non-zero → true
+    if (isNumberValue(value)) {
+      return Boolean(value);
+    }
+
+    // Convert recognized string values
+    if (isStringValue(value)) {
+      if (isBooleanTrueString(value)) {
+        return true;
+      }
+      if (isBooleanFalseString(value)) {
+        return false;
+      }
+    }
+
+    // Return original value for unrecognized strings or non-convertible types
+    return value;
+  }
+
+  // For string, object, and array types, return value as-is (no conversion)
+  return value;
+};
+
+export default normalizeType;

package/src/helpers/nullifyEmptyValues.ts

@@ -0,0 +1,207 @@
+import { get, set } from 'lodash';
+import { schemaSymbol, jsonSymbol, type SchemaErrorDetail } from 'z-schema';
+
+import type { TargetObject } from './JsonSchema';
+
+/**
+ * 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'
+] as const;
+
+/**
+ * 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)
+ */
+const nullifyEmptyValues = (
+  object: TargetObject,
+  validationErrors: SchemaErrorDetail[]
+): [TargetObject, SchemaErrorDetail[]] => {
+  // Create a deep clone to avoid mutating the original object
+  const result = JSON.parse(JSON.stringify(object)) as TargetObject;
+  const remainingErrors: SchemaErrorDetail[] = [];
+
+  for (const error of validationErrors) {
+    const { code, path: pathString } = error;
+    const schema = get(error, 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]);
+
+    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 = get(error, jsonSymbol) as TargetObject;
+    const value = get(json, path);
+
+    const isEmptyValue = EMPTY_VALUES.includes(value as typeof EMPTY_VALUES[number]);
+    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
+    set(result, path, null);
+  }
+
+  return [result, remainingErrors];
+};
+
+export default nullifyEmptyValues;

package/src/helpers/removeRequiredAndDefault.ts

@@ -0,0 +1,151 @@
+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
+ */
+const removeRequiredAndDefault = (jsonSchema: PropertySchema | EnumSchema) => {
+  const { properties } = (jsonSchema as ObjectPropertySchema);
+
+  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 as ObjectPropertySchema | ArrayPropertySchema);
+
+    const isObject = type === 'object';
+    const isArray = type === 'array';
+
+    if (isObject) {
+      // Recursively process nested object properties
+      removeRequiredAndDefault(property as ObjectPropertySchema);
+      continue;
+    }
+
+    if (isArray) {
+      const { items } = (property as ArrayPropertySchema);
+      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 };
+};
+
+export default removeRequiredAndDefault;

package/src/helpers/validateId.ts

@@ -0,0 +1,53 @@
+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:`.
+ */
+const validateId = (name: string, value: string | null | undefined) => {
+  if (!value) {
+    throw new Error(`Parameter "${name}" is required`);
+  }
+
+  const isURI = value.toLowerCase().startsWith('did:') || isURL(value);
+
+  if (isURI) {
+    return;
+  }
+
+  throw new Error(`Parameter "${name}" must be a URL, received: "${value}"`);
+};
+
+export default validateId;

package/src/index.ts

@@ -0,0 +1,13 @@
+import Schema from './Schema';
+import Validator from './Validator';
+import documentLoader from './ld/documentLoader';
+import ValidationError from './ValidationError';
+import CredentialFactory from './CredentialFactory';
+
+export {
+  Schema,
+  Validator,
+  documentLoader,
+  ValidationError,
+  CredentialFactory
+};