@kravc/schema 2.7.5 → 2.8.0-alpha.0

package/src/helpers/normalizeProperties.ts

@@ -0,0 +1,249 @@
+import { get, set, isUndefined } from 'lodash';
+
+import type {
+  EnumSchema,
+  PropertiesSchema,
+  ObjectPropertySchema,
+  ReferencePropertySchema,
+  ArrayPropertySchema
+} from './JsonSchema';
+
+/**
+ * Normalizes JSON schema properties by ensuring all properties have an explicit `type` attribute.
+ * 
+ * **Intent:**
+ * This function transforms schemas that may have implicit or missing type information into
+ * fully normalized schemas with explicit types. It recursively processes nested structures
+ * (objects and arrays) to ensure type consistency throughout the schema hierarchy.
+ * 
+ * **Use Cases:**
+ * - **Schema Validation Preparation**: Ensures schemas are ready for validation where type
+ *   information is required by validators or processing tools
+ * - **External Schema Normalization**: Normalizes schemas imported from external sources
+ *   (e.g., OpenAPI specs, YAML schemas) that may omit type information
+ * - **Type Inference**: Automatically infers types from structural hints (e.g., presence of
+ *   `properties` implies `object`, presence of `items` implies `array`)
+ * - **Schema Consistency**: Guarantees consistent schema structure before further processing
+ *   or transformation
+ * - **Default Type Assignment**: Provides sensible defaults (e.g., `string` for primitives)
+ *   when type cannot be inferred
+ * 
+ * **Behavior:**
+ * - **Enum Schemas**: Sets `type` to `'string'` if missing (preserves existing type if present)
+ * - **Reference Properties**: Skips `$ref` properties (they don't need type normalization)
+ * - **Type Inference Priority** (when type is missing):
+ *   1. If property has `properties` → sets `type: 'object'`
+ *   2. Else if property has `items` → sets `type: 'array'`
+ *   3. Else → sets `type: 'string'` (default)
+ * - **Object Properties**: 
+ *   - Infers `type: 'object'` from presence of `properties` (if type not already set)
+ *   - Creates empty `properties: {}` if `type: 'object'` but no properties exist
+ *   - Recursively normalizes nested object properties
+ *   - Note: If both `properties` and `items` exist, `properties` takes precedence
+ * - **Array Properties**:
+ *   - Infers `type: 'array'` from presence of `items` (if type not already set)
+ *   - Sets default `items: { type: 'string' }` if array has no items
+ *   - Normalizes item schemas: sets `type: 'object'` if items have `properties` (not undefined)
+ *     - `properties: null` → treated as having properties (sets type to 'object')
+ *     - `properties: undefined` → treated as not having properties (no type set)
+ *     - Empty object `{}` → treated as not having properties (no type set)
+ *   - Recursively normalizes nested properties within array items
+ * - **Primitive Properties**: Sets `type: 'string'` as default when no type, items, or properties exist
+ * - **Existing Types**: Never overrides existing type values (even if structure suggests different type)
+ * - **Edge Cases**:
+ *   - Empty schemas (`{}`) are handled gracefully
+ *   - Properties with conflicting structure (e.g., `type: 'object'` with `items`) are normalized
+ *     according to the explicit type, ignoring conflicting structural hints
+ * 
+ * **Examples:**
+ * 
+ * @example Enum schema normalization
+ * ```typescript
+ * const schema: EnumSchema = { enum: ['red', 'green', 'blue'] };
+ * normalizeProperties(schema);
+ * // Result: { enum: ['red', 'green', 'blue'], type: 'string' }
+ * ```
+ * 
+ * @example Object type inference
+ * ```typescript
+ * const schema: PropertiesSchema = {
+ *   user: {
+ *     properties: {
+ *       name: {}
+ *     }
+ *   }
+ * };
+ * normalizeProperties(schema);
+ * // Result:
+ * // {
+ * //   user: {
+ * //     type: 'object',
+ * //     properties: {
+ * //       name: { type: 'string' }
+ * //     }
+ * //   }
+ * // }
+ * ```
+ * 
+ * @example Array type inference
+ * ```typescript
+ * const schema: PropertiesSchema = {
+ *   tags: {
+ *     items: { type: 'string' }
+ *   }
+ * };
+ * normalizeProperties(schema);
+ * // Result:
+ * // {
+ * //   tags: {
+ * //     type: 'array',
+ * //     items: { type: 'string' }
+ * //   }
+ * // }
+ * ```
+ * 
+ * @example Complex nested structure
+ * ```typescript
+ * const schema: PropertiesSchema = {
+ *   profile: {
+ *     properties: {
+ *       name: {},
+ *       addresses: {
+ *         items: {
+ *           properties: {
+ *             street: {},
+ *             city: {}
+ *           }
+ *         }
+ *       }
+ *     }
+ *   }
+ * };
+ * normalizeProperties(schema);
+ * // Result:
+ * // {
+ * //   profile: {
+ * //     type: 'object',
+ * //     properties: {
+ * //       name: { type: 'string' },
+ * //       addresses: {
+ * //         type: 'array',
+ * //         items: {
+ * //           type: 'object',
+ * //           properties: {
+ * //             street: { type: 'string' },
+ * //             city: { type: 'string' }
+ * //           }
+ * //         }
+ * //       }
+ * //     }
+ * //   }
+ * // }
+ * ```
+ * 
+ * @example Reference properties are skipped
+ * ```typescript
+ * const schema: PropertiesSchema = {
+ *   refField: { $ref: '#/definitions/User' },
+ *   normalField: {}
+ * };
+ * normalizeProperties(schema);
+ * // Result:
+ * // {
+ * //   refField: { $ref: '#/definitions/User' }, // Unchanged
+ * //   normalField: { type: 'string' }
+ * // }
+ * ```
+ * 
+ * @example Default type assignment
+ * ```typescript
+ * const schema: PropertiesSchema = {
+ *   title: {},
+ *   count: { type: 'number' }
+ * };
+ * normalizeProperties(schema);
+ * // Result:
+ * // {
+ * //   title: { type: 'string' }, // Default assigned
+ * //   count: { type: 'number' }  // Existing preserved
+ * // }
+ * ```
+ * 
+ * @param schema - The schema to normalize (either an EnumSchema or PropertiesSchema)
+ * @modifies The schema object is mutated in place with normalized types
+ */
+const normalizeProperties = (schema: EnumSchema | PropertiesSchema) => {
+  const { enum: isEnum } = (schema as EnumSchema);
+
+  if (isEnum) {
+    const enumSchema = (schema as EnumSchema);
+    enumSchema.type = enumSchema.type || 'string';
+
+    return;
+  }
+
+  const properties = (schema as PropertiesSchema);
+
+  for (const name in properties) {
+    const property = properties[name];
+
+    const { $ref: isRef } = (property as ReferencePropertySchema);
+
+    if (isRef) {
+      continue;
+    }
+
+    const hasType = !!get(property, 'type');
+    const hasItems = !!get(property, 'items');
+    const hasProperties = !!get(property, 'properties');
+
+    if (!hasType) {
+      if (hasProperties) {
+        set(property, 'type', 'object');
+
+      } else if (hasItems) {
+        set(property, 'type', 'array');
+
+      } else {
+        set(property, 'type', 'string');
+
+      }
+    }
+
+    const type = get(property, 'type');
+
+    const isObject = type === 'object';
+
+    if (isObject) {
+      if (!hasProperties) {
+        (property as ObjectPropertySchema).properties = {};
+      }
+
+      // istanbul ignore next - unreachable defensive code: properties is always set to {} above if missing
+      normalizeProperties((property as ObjectPropertySchema).properties || {});
+    }
+
+    const isArray = type === 'array';
+
+    if (isArray) {
+      if (hasItems) {
+        // istanbul ignore next - unreachable defensive code: if items is undefined, hasItems would be false
+        const { items = {} } = (property as ArrayPropertySchema);
+
+        const isItemObject = !isUndefined((items as ObjectPropertySchema).properties);
+
+        if (isItemObject) {
+          set(items, 'type', 'object');
+
+          normalizeProperties((items as ObjectPropertySchema).properties || {});
+        }
+
+      } else {
+        (property as ArrayPropertySchema).items = { type: 'string' };
+
+      }
+    }
+  }
+};
+
+export default normalizeProperties;

package/src/helpers/normalizeRequired.ts

@@ -0,0 +1,233 @@
+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 { enum: enumItems } = (jsonSchema as EnumSchema);
+
+  const isEnum = !!enumItems;
+
+  if (isEnum) {
+    return;
+  }
+
+  const objectSchema = (jsonSchema as ObjectSchema);
+  const { properties } = objectSchema;
+
+  if (!properties) {
+    return;
+  }
+
+  const required = [];
+
+  for (const propertyName in properties) {
+    const property = properties[propertyName];
+
+    const { $ref: refSchemaId } = (property as ReferencePropertySchema);
+
+    const isReference = !isUndefined(refSchemaId);
+
+    // Handle required flag for all properties (including references)
+    if (property.required) {
+      property['x-required'] = true;
+      required.push(propertyName);
+    }
+
+    // Delete required property for all properties (whether true or false)
+    delete property.required;
+
+    // Skip recursive processing for reference properties
+    if (isReference) {
+      continue;
+    }
+
+    const { type } = (property as ObjectPropertySchema | ArrayPropertySchema);
+
+    const isObject = type === 'object';
+
+    if (isObject) {
+      normalizeRequired(property as ObjectPropertySchema);
+      continue;
+    }
+
+    const isArray = type === 'array';
+
+    if (isArray) {
+      const { items } = (property as ArrayPropertySchema);
+
+      if (items) {
+        normalizeRequired(items as ObjectPropertySchema | ReferencePropertySchema);
+      }
+
+      continue;
+    }
+  }
+
+  if (required.length > 0) {
+    objectSchema.required = required;
+  }
+};
+
+export default normalizeRequired;