@kravc/schema 2.7.6 → 2.8.0-alpha.1

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,17 @@
+import got from './helpers/got';
+import Schema from './Schema';
+import Validator from './Validator';
+import documentLoader from './ld/documentLoader';
+import ValidationError from './ValidationError';
+import createSchemasMap from './helpers/createSchemasMap';
+import CredentialFactory from './CredentialFactory';
+
+export {
+  got,
+  Schema,
+  Validator,
+  documentLoader,
+  ValidationError,
+  createSchemasMap,
+  CredentialFactory
+};

package/src/ld/__tests__/documentLoader.test.ts

@@ -0,0 +1,57 @@
+import documentLoader from '../documentLoader';
+import { constants } from 'credentials-context';
+
+describe('documentLoader(documentUrl)', () => {
+  describe('successful loading', () => {
+    it('should return document for valid credentials context URL', () => {
+      const result = documentLoader(constants.CREDENTIALS_CONTEXT_V1_URL);
+
+      expect(result).toHaveProperty('document');
+      expect(result).toHaveProperty('contextUrl', null);
+      expect(result).toHaveProperty('documentUrl', constants.CREDENTIALS_CONTEXT_V1_URL);
+      expect(result.document).toBeDefined();
+      expect(typeof result.document).toBe('object');
+    });
+
+    it('should handle URL with fragment', () => {
+      const urlWithFragment = `${constants.CREDENTIALS_CONTEXT_V1_URL}#VerifiableCredential`;
+      const result = documentLoader(urlWithFragment);
+
+      expect(result).toHaveProperty('document');
+      expect(result).toHaveProperty('documentUrl', urlWithFragment);
+      expect(result.document).toBeDefined();
+    });
+
+    it('should return correct structure', () => {
+      const result = documentLoader(constants.CREDENTIALS_CONTEXT_V1_URL);
+
+      expect(result).toEqual({
+        document: expect.any(Object),
+        contextUrl: null,
+        documentUrl: constants.CREDENTIALS_CONTEXT_V1_URL
+      });
+    });
+  });
+
+  describe('error handling', () => {
+    it('should throw error if context not found', () => {
+      expect(() => {
+        documentLoader('https://example.com/unknown-context');
+      }).toThrow('Custom context "https://example.com/unknown-context" is not supported');
+    });
+
+    it('should throw error with full URL including fragment when context not found', () => {
+      const urlWithFragment = 'https://example.com/unknown-context#fragment';
+
+      expect(() => {
+        documentLoader(urlWithFragment);
+      }).toThrow('Custom context "https://example.com/unknown-context#fragment" is not supported');
+    });
+
+    it('should throw error for empty string', () => {
+      expect(() => {
+        documentLoader('');
+      }).toThrow('Custom context "" is not supported');
+    });
+  });
+});

package/src/ld/__tests__/getLinkedDataAttributeType.test.ts

@@ -0,0 +1,212 @@
+import getLinkedDataAttributeType, { type PropertySchema } from '../getLinkedDataAttributeType';
+
+describe('getLinkedDataAttributeType(propertySchema)', () => {
+  describe('when @type is defined', () => {
+    it('should return the @type value when it is a string', () => {
+      const propertySchema: PropertySchema = {
+        '@type': 'schema:Text',
+        type: 'string',
+      };
+      expect(getLinkedDataAttributeType(propertySchema)).toBe('schema:Text');
+    });
+
+    it('should return the @type value even when type and format are present', () => {
+      const propertySchema: PropertySchema = {
+        '@type': 'schema:CustomType',
+        type: 'number',
+        format: 'date',
+      };
+      expect(getLinkedDataAttributeType(propertySchema)).toBe('schema:CustomType');
+    });
+
+    it('should return the @type value for integer type', () => {
+      const propertySchema: PropertySchema = {
+        '@type': 'schema:CustomInteger',
+        type: 'integer',
+      };
+      expect(getLinkedDataAttributeType(propertySchema)).toBe('schema:CustomInteger');
+    });
+  });
+
+  describe('when type is integer', () => {
+    it('should return schema:Integer for integer type', () => {
+      const propertySchema: PropertySchema = {
+        type: 'integer',
+      };
+      expect(getLinkedDataAttributeType(propertySchema)).toBe('schema:Integer');
+    });
+
+    it('should return schema:Integer even when format is present', () => {
+      const propertySchema: PropertySchema = {
+        type: 'integer',
+        format: 'int32',
+      };
+      expect(getLinkedDataAttributeType(propertySchema)).toBe('schema:Integer');
+    });
+  });
+
+  describe('when type is number', () => {
+    it('should return schema:Number for number type', () => {
+      const propertySchema: PropertySchema = {
+        type: 'number',
+      };
+      expect(getLinkedDataAttributeType(propertySchema)).toBe('schema:Number');
+    });
+
+    it('should return schema:Number even when format is present', () => {
+      const propertySchema: PropertySchema = {
+        type: 'number',
+        format: 'float',
+      };
+      expect(getLinkedDataAttributeType(propertySchema)).toBe('schema:Number');
+    });
+  });
+
+  describe('when format is date', () => {
+    it('should return schema:Date for date format', () => {
+      const propertySchema: PropertySchema = {
+        type: 'string',
+        format: 'date',
+      };
+      expect(getLinkedDataAttributeType(propertySchema)).toBe('schema:Date');
+    });
+
+    it('should return schema:Date regardless of type when format is date', () => {
+      const propertySchema: PropertySchema = {
+        type: 'object',
+        format: 'date',
+      };
+      expect(getLinkedDataAttributeType(propertySchema)).toBe('schema:Date');
+    });
+  });
+
+  describe('when format is date-time', () => {
+    it('should return schema:DateTime for date-time format', () => {
+      const propertySchema: PropertySchema = {
+        type: 'string',
+        format: 'date-time',
+      };
+      expect(getLinkedDataAttributeType(propertySchema)).toBe('schema:DateTime');
+    });
+
+    it('should return schema:DateTime when format is date-time and type is string', () => {
+      const propertySchema: PropertySchema = {
+        type: 'string',
+        format: 'date-time',
+      };
+      expect(getLinkedDataAttributeType(propertySchema)).toBe('schema:DateTime');
+    });
+
+    it('should prioritize type over format (number type wins over date-time format)', () => {
+      const propertySchema: PropertySchema = {
+        type: 'number',
+        format: 'date-time',
+      };
+      // The function checks type before format, so number type takes priority
+      expect(getLinkedDataAttributeType(propertySchema)).toBe('schema:Number');
+    });
+  });
+
+  describe('when no match is found', () => {
+    it('should return undefined for string type without format', () => {
+      const propertySchema: PropertySchema = {
+        type: 'string',
+      };
+      expect(getLinkedDataAttributeType(propertySchema)).toBeUndefined();
+    });
+
+    it('should return undefined for boolean type', () => {
+      const propertySchema: PropertySchema = {
+        type: 'boolean',
+      };
+      expect(getLinkedDataAttributeType(propertySchema)).toBeUndefined();
+    });
+
+    it('should return undefined for array type', () => {
+      const propertySchema: PropertySchema = {
+        type: 'array',
+      };
+      expect(getLinkedDataAttributeType(propertySchema)).toBeUndefined();
+    });
+
+    it('should return undefined for object type', () => {
+      const propertySchema: PropertySchema = {
+        type: 'object',
+      };
+      expect(getLinkedDataAttributeType(propertySchema)).toBeUndefined();
+    });
+
+    it('should return undefined for other formats', () => {
+      const propertySchema: PropertySchema = {
+        type: 'string',
+        format: 'email',
+      };
+      expect(getLinkedDataAttributeType(propertySchema)).toBeUndefined();
+    });
+
+    it('should return undefined for empty object', () => {
+      const propertySchema: PropertySchema = {} as PropertySchema;
+      expect(getLinkedDataAttributeType(propertySchema)).toBeUndefined();
+    });
+
+    it('should return undefined when only $ref is present', () => {
+      const propertySchema: PropertySchema = {
+        $ref: '#/definitions/SomeType',
+      };
+      expect(getLinkedDataAttributeType(propertySchema)).toBeUndefined();
+    });
+  });
+
+  describe('priority order', () => {
+    it('should prioritize @type over type integer', () => {
+      const propertySchema: PropertySchema = {
+        '@type': 'schema:Custom',
+        type: 'integer',
+      };
+      expect(getLinkedDataAttributeType(propertySchema)).toBe('schema:Custom');
+    });
+
+    it('should prioritize @type over format date', () => {
+      const propertySchema: PropertySchema = {
+        '@type': 'schema:Custom',
+        format: 'date',
+      };
+      expect(getLinkedDataAttributeType(propertySchema)).toBe('schema:Custom');
+    });
+
+    it('should prioritize integer type over number type', () => {
+      const propertySchema: PropertySchema = {
+        type: 'integer',
+        format: 'number',
+      };
+      expect(getLinkedDataAttributeType(propertySchema)).toBe('schema:Integer');
+    });
+
+    it('should prioritize integer type over date format', () => {
+      const propertySchema: PropertySchema = {
+        type: 'integer',
+        format: 'date',
+      };
+      expect(getLinkedDataAttributeType(propertySchema)).toBe('schema:Integer');
+    });
+
+    it('should prioritize number type over date format', () => {
+      const propertySchema: PropertySchema = {
+        type: 'number',
+        format: 'date',
+      };
+      expect(getLinkedDataAttributeType(propertySchema)).toBe('schema:Number');
+    });
+
+    it('should prioritize date format over date-time format when both are present (date checked first)', () => {
+      // NOTE: This tests the actual implementation order.
+      //       The function checks date before date-time, so date would win if both were somehow set.
+      //       But in practice, format can only be one value, so this is more of an edge case test.
+      const propertySchema: PropertySchema = {
+        type: 'string',
+        format: 'date',
+      };
+      expect(getLinkedDataAttributeType(propertySchema)).toBe('schema:Date');
+    });
+  });
+});