@plasius/schema 1.1.1 → 1.2.0

package/dist/index.cjs

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   FieldBuilder: () => FieldBuilder,
+  IsoLanguageCode: () => IsoLanguageCode,
   createComponentSchema: () => createComponentSchema,
   createSchema: () => createSchema,
   field: () => field,
@@ -28,13 +29,23 @@ __export(index_exports, {
   getAllSchemas: () => getAllSchemas,
   getComponentSchema: () => getComponentSchema,
   getSchemaForType: () => getSchemaForType,
+  isExtensionSingleton: () => isExtensionSingleton,
+  isExtensionSubtag: () => isExtensionSubtag,
+  isIsoLanguageCode: () => isIsoLanguageCode,
+  isPrivateUseSingleton: () => isPrivateUseSingleton,
+  isPrivateUseSubtag: () => isPrivateUseSubtag,
+  isRegionSubtag: () => isRegionSubtag,
+  isScriptSubtag: () => isScriptSubtag,
+  isVariantSubtag: () => isVariantSubtag,
   isoCountryCodes: () => isoCountryCodes,
   isoCurrencyCodes: () => isoCurrencyCodes,
   registerComponentSchema: () => registerComponentSchema,
+  renderSchemaDescription: () => renderSchemaDescription,
   validateCountryCode: () => validateCountryCode,
   validateCurrencyCode: () => validateCurrencyCode,
   validateDateTimeISO: () => validateDateTimeISO,
   validateEmail: () => validateEmail,
+  validateLanguage: () => validateLanguage,
   validateName: () => validateName,
   validatePercentage: () => validatePercentage,
   validatePhone: () => validatePhone,
@@ -466,6 +477,7 @@ var isoCountryCodes = /* @__PURE__ */ new Set([
   "PM",
   "PN",
   "PR",
+  "PS",
   "PT",
   "PW",
   "PY",
@@ -668,6 +680,7 @@ var isoCurrencyCodes = /* @__PURE__ */ new Set([
   "SEK",
   "SGD",
   "SHP",
+  "SLE",
   "SLL",
   "SOS",
   "SRD",
@@ -1153,49 +1166,151 @@ function enforcePIIField(parentKey, key, value, def, enforcement = "none", error
   return { shortCircuit: false };
 }
 function prepareForStorage(shape, input, encryptFn, hashFn) {
-  const result = {};
-  for (const key in shape) {
-    const def = shape[key];
-    if (!def) continue;
-    const value = input[key];
+  const build = (def, value, key, out, ctx = {}) => {
+    if (!def) return;
+    const isMissing = value === void 0 || value === null;
     if (def._pii?.action === "encrypt") {
-      result[key + "Encrypted"] = encryptFn(value);
-    } else if (def._pii?.action === "hash") {
-      result[key + "Hash"] = hashFn(value);
-    } else {
-      result[key] = value;
+      if (!isMissing) out[key + "Encrypted"] = encryptFn(value);
+      return;
+    }
+    if (def._pii?.action === "hash") {
+      if (!isMissing) out[key + "Hash"] = hashFn(value);
+      return;
+    }
+    if (def._pii?.action === "clear") {
+      if (!isMissing) out[key] = null;
+      return;
+    }
+    if (def.type === "object" && def._shape) {
+      const obj = {};
+      for (const [childKey, childDef] of Object.entries(def._shape)) {
+        build(childDef, value?.[childKey], childKey, obj, { parentKey: key });
+      }
+      out[key] = obj;
+      return;
+    }
+    if (def.type === "array" && def.itemType && Array.isArray(value)) {
+      out[key] = value.map((item) => {
+        const obj = {};
+        build(def.itemType, item, key, obj, {
+          parentKey: key,
+          isArrayItem: true
+        });
+        if (Object.prototype.hasOwnProperty.call(obj, key)) {
+          return obj[key];
+        }
+        return Object.keys(obj).length > 0 ? obj : item;
+      });
+      return;
+    }
+    if (def.type === "ref") {
+      const ref = { ...value };
+      const refShape = def._shape;
+      if (refShape && value) {
+        for (const [childKey, childDef] of Object.entries(refShape)) {
+          build(childDef, value[childKey], childKey, ref, { parentKey: key });
+        }
+      }
+      out[key] = ref;
+      return;
     }
+    out[key] = value;
+  };
+  const result = {};
+  for (const key in shape) {
+    build(shape[key], input?.[key], key, result);
   }
   return result;
 }
 function prepareForRead(shape, stored, decryptFn) {
+  const readValue = (def, key, container, ctx = {}) => {
+    if (!def) return container?.[key];
+    const action = def._pii?.action;
+    if (action === "encrypt") {
+      const enc = container?.[key + "Encrypted"] ?? container?.[`${ctx.parentKey ?? key}Encrypted`];
+      return enc === void 0 ? void 0 : decryptFn(enc);
+    }
+    if (action === "hash") {
+      const h = container?.[key + "Hash"] ?? container?.[`${ctx.parentKey ?? key}Hash`];
+      return h === void 0 ? void 0 : h;
+    }
+    if (action === "clear")
+      return container?.hasOwnProperty(key) ? null : void 0;
+    if (def.type === "object" && def._shape) {
+      const obj = {};
+      const source = container && Object.prototype.hasOwnProperty.call(container, key) ? container[key] : container ?? {};
+      for (const [childKey, childDef] of Object.entries(def._shape)) {
+        obj[childKey] = readValue(childDef, childKey, source);
+      }
+      return obj;
+    }
+    if (def.type === "array" && def.itemType) {
+      const arr = container?.[key];
+      if (!Array.isArray(arr)) return arr;
+      return arr.map(
+        (item) => readValue(def.itemType, key, item, { parentKey: key, isArrayItem: true })
+      );
+    }
+    if (def.type === "ref") {
+      const ref = { ...container?.[key] ?? {} };
+      const refShape = def._shape;
+      if (refShape) {
+        for (const [childKey, childDef] of Object.entries(refShape)) {
+          ref[childKey] = readValue(childDef, childKey, ref);
+        }
+      }
+      return ref;
+    }
+    return container?.[key];
+  };
   const result = {};
   for (const key in shape) {
-    const def = shape[key];
-    if (!def) continue;
-    if (def._pii?.action === "encrypt") {
-      result[key] = decryptFn(stored[key + "Encrypted"]);
-    } else {
-      result[key] = stored[key];
-    }
+    result[key] = readValue(shape[key], key, stored);
   }
   return result;
 }
 function sanitizeForLog(shape, data, pseudonymFn) {
-  const output = {};
-  for (const key in shape) {
-    const def = shape[key];
-    if (!def) continue;
-    const value = data[key];
+  const visit = (def, value, ctx = {}) => {
+    if (!def) return void 0;
     const handling = def._pii?.logHandling;
-    if (handling === "omit") continue;
-    if (handling === "redact") {
-      output[key] = "[REDACTED]";
-    } else if (handling === "pseudonym") {
-      output[key] = pseudonymFn(value);
-    } else {
-      output[key] = value;
+    if (handling === "omit") return void 0;
+    if (handling === "redact") return "[REDACTED]";
+    if (handling === "pseudonym") return pseudonymFn(value);
+    if (def.type === "object" && def._shape) {
+      const obj = {};
+      const src = value ?? {};
+      for (const [k, childDef] of Object.entries(def._shape)) {
+        const child = visit(childDef, src[k], { parentKey: k });
+        if (child !== void 0) obj[k] = child;
+      }
+      return obj;
+    }
+    if (def.type === "array" && def.itemType) {
+      if (!Array.isArray(value)) return void 0;
+      const arr = value.map((v) => visit(def.itemType, v, { parentKey: ctx.parentKey })).filter((v) => v !== void 0);
+      return arr;
+    }
+    if (def.type === "ref") {
+      const ref = value ? { type: value.type, id: value.id } : {};
+      const refShape = def._shape;
+      const src = value ?? {};
+      if (refShape) {
+        for (const [k, childDef] of Object.entries(refShape)) {
+          const child = visit(childDef, src[k]);
+          if (child !== void 0) ref[k] = child;
+        }
+      } else if (value) {
+        ref.type = value.type;
+        ref.id = value.id;
+      }
+      return ref;
     }
+    return value;
+  };
+  const output = {};
+  for (const key in shape) {
+    const child = visit(shape[key], data?.[key]);
+    if (child !== void 0) output[key] = child;
   }
   return output;
 }
@@ -1217,23 +1332,106 @@ function getPiiAudit(shape) {
   return piiFields;
 }
 function scrubPiiForDelete(shape, stored) {
-  const result = { ...stored };
-  for (const key in shape) {
-    const def = shape[key];
-    if (!def) continue;
+  const result = Array.isArray(stored) ? [...stored] : { ...stored };
+  const setAtPath = (target, path, val) => {
+    let cur = target;
+    for (let i = 0; i < path.length - 1; i++) {
+      const p = path[i];
+      if (p === void 0) return;
+      if (cur[p] === void 0) {
+        const next = path[i + 1];
+        cur[p] = typeof next === "number" ? [] : {};
+      }
+      cur = cur[p];
+    }
+    const last = path[path.length - 1];
+    if (last === void 0) return;
+    cur[last] = val;
+  };
+  const visit = (def, host, path, keyName) => {
+    if (!def) return;
+    const applyPath = (targetKey) => {
+      const last = path[path.length - 1];
+      if (last === void 0) return;
+      if (typeof last === "number") {
+        setAtPath(result, [...path, targetKey], null);
+      } else {
+        setAtPath(result, [...path.slice(0, -1), targetKey], null);
+      }
+    };
     if (def._pii?.action === "encrypt") {
-      result[key + "Encrypted"] = null;
-    } else if (def._pii?.action === "hash") {
-      result[key + "Hash"] = null;
-    } else if (def._pii?.action === "clear") {
-      result[key] = null;
+      const targetKey = `${keyName}Encrypted`;
+      if (host && Object.prototype.hasOwnProperty.call(host, targetKey)) {
+        applyPath(targetKey);
+      }
+      return;
     }
+    if (def._pii?.action === "hash") {
+      const targetKey = `${keyName}Hash`;
+      if (host && Object.prototype.hasOwnProperty.call(host, targetKey)) {
+        applyPath(targetKey);
+      }
+      return;
+    }
+    if (def._pii?.action === "clear") {
+      if (host && Object.prototype.hasOwnProperty.call(host, keyName)) {
+        setAtPath(result, path, null);
+      }
+      return;
+    }
+    if (def.type === "object" && def._shape) {
+      const obj = host && Object.prototype.hasOwnProperty.call(host, keyName) ? host[keyName] : host;
+      for (const [k, childDef] of Object.entries(def._shape)) {
+        visit(childDef, obj, [...path, k], k);
+      }
+      return;
+    }
+    if (def.type === "array" && def.itemType) {
+      const arr = host?.[keyName];
+      if (Array.isArray(arr)) {
+        arr.forEach(
+          (item, idx) => visit(def.itemType, item, [...path, idx], keyName)
+        );
+      }
+      return;
+    }
+    if (def.type === "ref") {
+      const refShape = def._shape;
+      const ref = host?.[keyName];
+      if (refShape && ref) {
+        for (const [k, childDef] of Object.entries(refShape)) {
+          visit(childDef, ref, [...path, k], k);
+        }
+      }
+    }
+  };
+  for (const key in shape) {
+    visit(shape[key], stored, [key], key);
   }
   return result;
 }
 
 // src/schema.ts
 var globalSchemaRegistry = /* @__PURE__ */ new Map();
+function deepClone(value) {
+  const seen = /* @__PURE__ */ new WeakMap();
+  const cloneAny = (val) => {
+    if (val === null || typeof val !== "object") return val;
+    if (seen.has(val)) throw new TypeError("Cannot clone circular structures");
+    if (val instanceof Date) return new Date(val.getTime());
+    if (Array.isArray(val)) {
+      const arr = [];
+      seen.set(val, arr);
+      val.forEach((item) => arr.push(cloneAny(item)));
+      return arr;
+    }
+    const out = {};
+    seen.set(val, out);
+    for (const [k, v] of Object.entries(val)) out[k] = cloneAny(v);
+    return out;
+  };
+  return cloneAny(value);
+}
 function cmpSemver(a, b) {
   const pa = a.split(".").map((n) => parseInt(n, 10));
   const pb = b.split(".").map((n) => parseInt(n, 10));
@@ -1292,8 +1490,17 @@ function getEnumValues(def) {
   );
   return ok ? src : void 0;
 }
+function applyDefault(def, current) {
+  if ((current === void 0 || current === null) && typeof def?.getDefault === "function") {
+    const next = def.getDefault();
+    if (next !== void 0) {
+      return { value: next, applied: true };
+    }
+  }
+  return { value: current, applied: false };
+}
 function isOptional(def) {
-  return (def?.isRequired ?? false) === false;
+  return def?.isRequired === false;
 }
 function getValidator(def) {
   return def?._validator ?? void 0;
@@ -1345,10 +1552,18 @@ function validateStringField(parentKey, key, value, def, errors) {
     }
   }
 }
-function validateNumberField(parentKey, key, value, _def, errors) {
-  const enumPath = parentKey ? `${parentKey}.${key}` : key;
+function validateNumberField(parentKey, key, value, def, errors) {
+  const path = parentKey ? `${parentKey}.${key}` : key;
   if (typeof value !== "number") {
-    errors.push(`Field ${enumPath} must be number`);
+    errors.push(`Field ${path} must be number`);
+    return;
+  }
+  const enumValues = getEnumValues(def);
+  if (Array.isArray(enumValues)) {
+    const enumError = validateEnum(path, value, enumValues);
+    if (enumError) {
+      errors.push(enumError);
+    }
   }
 }
 function validateBooleanField(parentKey, key, value, _def, errors) {
@@ -1357,9 +1572,15 @@ function validateBooleanField(parentKey, key, value, _def, errors) {
     errors.push(`Field ${path} must be boolean`);
   }
 }
-function validateObjectChildren(parentKey, obj, shape, errors) {
+function validateObjectChildren(parentKey, obj, shape, errors, existing, piiEnforcement, logger) {
   for (const [childKey, childDef] of Object.entries(shape)) {
-    const childValue = obj[childKey];
+    let childValue = obj[childKey];
+    const existingChild = existing && typeof existing === "object" ? existing[childKey] : void 0;
+    const { value: withDefault, applied } = applyDefault(childDef, childValue);
+    if (applied) {
+      obj[childKey] = withDefault;
+      childValue = withDefault;
+    }
     const { missing } = checkMissingRequired(
       parentKey,
       childKey,
@@ -1368,6 +1589,25 @@ function validateObjectChildren(parentKey, obj, shape, errors) {
       errors
     );
     if (missing) continue;
+    const { immutableViolation } = checkImmutable(
+      parentKey,
+      childKey,
+      childValue,
+      childDef,
+      existing,
+      errors
+    );
+    if (immutableViolation) continue;
+    const { shortCircuit } = enforcePIIField(
+      parentKey,
+      childKey,
+      childValue,
+      childDef,
+      piiEnforcement,
+      errors,
+      logger
+    );
+    if (shortCircuit) continue;
     const { invalid } = runCustomValidator(
       parentKey,
       childKey,
@@ -1376,17 +1616,27 @@ function validateObjectChildren(parentKey, obj, shape, errors) {
       errors
     );
     if (invalid) continue;
-    validateByType(parentKey, childKey, childValue, childDef, errors);
+    validateByType(
+      parentKey,
+      childKey,
+      childValue,
+      childDef,
+      errors,
+      existingChild,
+      piiEnforcement,
+      logger
+    );
   }
 }
-function validateObjectField(parentKey, key, value, def, errors) {
+function validateObjectField(parentKey, key, value, def, errors, existing, piiEnforcement, logger) {
   const path = parentKey ? `${parentKey}.${key}` : key;
   if (typeof value !== "object" || value === null || Array.isArray(value)) {
     errors.push(`Field ${path} must be object`);
     return;
   }
   const objShape = getShape(def);
-  if (objShape) validateObjectChildren(path, value, objShape, errors);
+  if (objShape)
+    validateObjectChildren(path, value, objShape, errors, existing, piiEnforcement, logger);
 }
 function validateArrayOfStrings(parentKey, key, arr, itemDef, errors) {
   const path = parentKey ? `${parentKey}.${key}` : key;
@@ -1401,6 +1651,14 @@ function validateArrayOfStrings(parentKey, key, arr, itemDef, errors) {
       errors.push(enumError);
     }
   }
+  const validator = getValidator(itemDef);
+  if (validator) {
+    arr.forEach((v, idx) => {
+      if (!validator(v)) {
+        errors.push(`Invalid value for field: ${path}[${idx}]`);
+      }
+    });
+  }
 }
 function validateArrayOfNumbers(parentKey, key, arr, itemDef, errors) {
   const path = parentKey ? `${parentKey}.${key}` : key;
@@ -1414,14 +1672,30 @@ function validateArrayOfNumbers(parentKey, key, arr, itemDef, errors) {
       errors.push(enumError);
     }
   }
+  const validator = getValidator(itemDef);
+  if (validator) {
+    arr.forEach((v, idx) => {
+      if (!validator(v)) {
+        errors.push(`Invalid value for field: ${path}[${idx}]`);
+      }
+    });
+  }
 }
 function validateArrayOfBooleans(parentKey, key, arr, _itemDef, errors) {
   const path = parentKey ? `${parentKey}.${key}` : key;
   if (!arr.every((v) => typeof v === "boolean")) {
     errors.push(`Field ${path} must be boolean[]`);
   }
+  const validator = getValidator(_itemDef);
+  if (validator) {
+    arr.forEach((v, idx) => {
+      if (!validator(v)) {
+        errors.push(`Invalid value for field: ${path}[${idx}]`);
+      }
+    });
+  }
 }
-function validateArrayOfObjects(parentKey, key, arr, itemDef, errors) {
+function validateArrayOfObjects(parentKey, key, arr, itemDef, errors, existing, piiEnforcement, logger) {
   const path = parentKey ? `${parentKey}.${key}` : key;
   if (!Array.isArray(arr) || !arr.every((v) => typeof v === "object" && v !== null && !Array.isArray(v))) {
     errors.push(`Field ${path} must be object[]`);
@@ -1431,8 +1705,18 @@ function validateArrayOfObjects(parentKey, key, arr, itemDef, errors) {
   if (!itemShape) return;
   arr.forEach((item, idx) => {
     const itemParent = `${path}[${idx}]`;
+    const existingItem = Array.isArray(existing) ? existing[idx] : void 0;
     for (const [childKey, childDef] of Object.entries(itemShape)) {
-      const childValue = item[childKey];
+      let childValue = item[childKey];
+      const existingChild = existingItem && typeof existingItem === "object" ? existingItem[childKey] : void 0;
+      const { value: withDefault, applied } = applyDefault(
+        childDef,
+        childValue
+      );
+      if (applied) {
+        item[childKey] = withDefault;
+        childValue = withDefault;
+      }
       const { missing } = checkMissingRequired(
         itemParent,
         childKey,
@@ -1441,6 +1725,25 @@ function validateArrayOfObjects(parentKey, key, arr, itemDef, errors) {
         errors
       );
       if (missing) continue;
+      const { immutableViolation } = checkImmutable(
+        itemParent,
+        childKey,
+        childValue,
+        childDef,
+        existingItem,
+        errors
+      );
+      if (immutableViolation) continue;
+      const { shortCircuit } = enforcePIIField(
+        itemParent,
+        childKey,
+        childValue,
+        childDef,
+        piiEnforcement,
+        errors,
+        logger
+      );
+      if (shortCircuit) continue;
       const { invalid } = runCustomValidator(
         itemParent,
         childKey,
@@ -1449,11 +1752,20 @@ function validateArrayOfObjects(parentKey, key, arr, itemDef, errors) {
         errors
       );
       if (invalid) continue;
-      validateByType(itemParent, childKey, childValue, childDef, errors);
+      validateByType(
+        itemParent,
+        childKey,
+        childValue,
+        childDef,
+        errors,
+        existingChild,
+        piiEnforcement,
+        logger
+      );
     }
   });
 }
-function validateArrayField(parentKey, key, value, def, errors) {
+function validateArrayField(parentKey, key, value, def, errors, existing, piiEnforcement, logger) {
   const path = parentKey ? `${parentKey}.${key}` : key;
   if (!Array.isArray(value)) {
     errors.push(`Field ${key} must be an array`);
@@ -1467,7 +1779,16 @@ function validateArrayField(parentKey, key, value, def, errors) {
   if (itemType === "boolean")
     return validateArrayOfBooleans(parentKey, key, value, def.itemType, errors);
   if (itemType === "object")
-    return validateArrayOfObjects(parentKey, key, value, def.itemType, errors);
+    return validateArrayOfObjects(
+      parentKey,
+      key,
+      value,
+      def.itemType,
+      errors,
+      existing,
+      piiEnforcement,
+      logger
+    );
   if (itemType === "ref") {
     const expectedType = def.itemType.refType;
     value.forEach((ref, idx) => {
@@ -1479,24 +1800,63 @@ function validateArrayField(parentKey, key, value, def, errors) {
     });
     const refShape = getShape(def.itemType);
     if (refShape) {
+      const existingRefs = Array.isArray(existing) ? existing : [];
       value.forEach((ref, idx) => {
         if (ref && typeof ref === "object" && ref !== null) {
+          const existingRef = existingRefs[idx];
           for (const [childKey, childDef] of Object.entries(refShape)) {
-            const childValue = ref[childKey];
+            const childPath = `${path}[${idx}].${childKey}`;
+            let childValue = ref[childKey];
+            const existingChild = existingRef && typeof existingRef === "object" ? existingRef[childKey] : void 0;
+            const { value: withDefault, applied } = applyDefault(
+              childDef,
+              childValue
+            );
+            if (applied) {
+              ref[childKey] = withDefault;
+              childValue = withDefault;
+            }
             if ((childValue === void 0 || childValue === null) && !isOptional(childDef)) {
-              errors.push(
-                `Missing required field: ${path}[${idx}].${childKey}`
-              );
+              errors.push(`Missing required field: ${childPath}`);
               continue;
             }
+            const { immutableViolation } = checkImmutable(
+              `${path}[${idx}]`,
+              childKey,
+              childValue,
+              childDef,
+              existingRef,
+              errors
+            );
+            if (immutableViolation) continue;
+            const { shortCircuit } = enforcePIIField(
+              `${path}[${idx}]`,
+              childKey,
+              childValue,
+              childDef,
+              piiEnforcement,
+              errors,
+              logger
+            );
+            if (shortCircuit) continue;
             const childValidator = getValidator(childDef);
             if (childValidator && childValue !== void 0 && childValue !== null) {
               const valid = childValidator(childValue);
-              if (!valid)
-                errors.push(
-                  `Invalid value for field: ${path}[${idx}].${childKey}`
-                );
+              if (!valid) {
+                errors.push(`Invalid value for field: ${childPath}`);
+                continue;
+              }
             }
+            validateByType(
+              `${path}[${idx}]`,
+              childKey,
+              childValue,
+              childDef,
+              errors,
+              existingChild,
+              piiEnforcement,
+              logger
+            );
           }
         }
       });
@@ -1505,13 +1865,20 @@ function validateArrayField(parentKey, key, value, def, errors) {
   }
   errors.push(`Field ${path} has unsupported array item type`);
 }
-function validateRefField(parentKey, key, value, _def, errors) {
+function validateRefField(parentKey, key, value, def, errors, _existing, _piiEnforcement, _logger) {
+  const path = parentKey ? `${parentKey}.${key}` : key;
   if (typeof value !== "object" || value === null || typeof value.type !== "string" || typeof value.id !== "string") {
-    const path = parentKey ? `${parentKey}.${key}` : key;
     errors.push(`Field ${path} must be { type: string; id: string }`);
+    return;
+  }
+  const expectedType = def.refType;
+  if (expectedType && value.type !== expectedType) {
+    errors.push(
+      `Field ${path} must reference type: ${expectedType} (got ${value.type})`
+    );
   }
 }
-function validateByType(parentKey, key, value, def, errors) {
+function validateByType(parentKey, key, value, def, errors, existing, piiEnforcement, logger) {
   const path = parentKey ? `${parentKey}.${key}` : key;
   switch (def.type) {
     case "string":
@@ -1521,11 +1888,29 @@ function validateByType(parentKey, key, value, def, errors) {
     case "boolean":
       return validateBooleanField(parentKey, key, value, def, errors);
     case "object":
-      return validateObjectField(parentKey, key, value, def, errors);
+      return validateObjectField(
+        parentKey,
+        key,
+        value,
+        def,
+        errors,
+        existing,
+        piiEnforcement,
+        logger
+      );
     case "array":
-      return validateArrayField(parentKey, key, value, def, errors);
+      return validateArrayField(
+        parentKey,
+        key,
+        value,
+        def,
+        errors,
+        existing,
+        piiEnforcement,
+        logger
+      );
     case "ref":
-      return validateRefField(parentKey, key, value, def, errors);
+      return validateRefField(parentKey, key, value, def, errors, existing, piiEnforcement, logger);
     default:
       errors.push(`Unknown type for field ${path}: ${def.type}`);
   }
@@ -1556,10 +1941,11 @@ function createSchema(_shape, entityType, options = {
     validate(input, existing) {
       const errors = [];
       const result = {};
+      const piiMode = options.piiEnforcement ?? "none";
       if (typeof input !== "object" || input === null) {
         return { valid: false, errors: ["Input must be an object"] };
       }
-      const working = { ...input };
+      const working = typeof input === "object" && input !== null ? deepClone(input) : { ...input };
       if (working.type == null) working.type = entityType;
       if (working.version == null) working.version = version;
       const fromVersion = String(working.version ?? "0.0.0");
@@ -1583,11 +1969,17 @@ function createSchema(_shape, entityType, options = {
       }
       for (const key in schema._shape) {
         const def = schema._shape[key];
-        const value = working[key];
+        let value = working[key];
+        const existingField = existing && typeof existing === "object" ? existing[key] : void 0;
         if (!def) {
           errors.push(`Field definition missing for: ${key}`);
           continue;
         }
+        const { value: withDefault, applied } = applyDefault(def, value);
+        if (applied) {
+          working[key] = withDefault;
+          value = withDefault;
+        }
         const { missing } = checkMissingRequired("", key, value, def, errors);
         if (missing) continue;
         const { immutableViolation } = checkImmutable(
@@ -1604,7 +1996,7 @@ function createSchema(_shape, entityType, options = {
           key,
           value,
           def,
-          options.piiEnforcement ?? "none",
+          piiMode,
           errors,
           console
         );
@@ -1619,7 +2011,7 @@ function createSchema(_shape, entityType, options = {
             localErrors
           );
           if (!invalid) {
-            validateByType("", key, val, def, localErrors);
+            validateByType("", key, val, def, localErrors, existingField, piiMode, console);
           }
           return localErrors;
         };
@@ -1741,13 +2133,20 @@ function createSchema(_shape, entityType, options = {
           log?.(`Skipping field ${key} (not in onlyFields)`);
           continue;
         }
-        const refType = def.refType;
         const autoValidate = def.autoValidate !== false;
         const refPolicy = def.refPolicy ?? "eager";
         const value = entity[key];
         if (!value) continue;
         if (def.type === "ref") {
+          const refType = def.refType;
+          if (!refType)
+            throw new Error(`Missing refType for reference field ${key}`);
           const ref = value;
+          if (ref.type && ref.type !== refType) {
+            throw new Error(
+              `Reference type mismatch for field ${key}: expected ${refType}, got ${ref.type}`
+            );
+          }
           const target = await options2.resolveEntity(refType, ref.id);
           if (!target)
             throw new Error(
@@ -1764,8 +2163,16 @@ function createSchema(_shape, entityType, options = {
             }
           }
         } else if (def.type === "array" && def.itemType?.type === "ref") {
+          const refType = def.itemType.refType;
+          if (!refType)
+            throw new Error(`Missing refType for reference array field ${key}`);
           const refs = value;
           for (const ref of refs) {
+            if (ref.type && ref.type !== refType) {
+              throw new Error(
+                `Reference type mismatch for field ${key}: expected ${refType}, got ${ref.type}`
+              );
+            }
             const target = await options2.resolveEntity(refType, ref.id);
             if (!target)
               throw new Error(
@@ -1856,12 +2263,16 @@ function createSchema(_shape, entityType, options = {
       for (const [key, def] of Object.entries(schema._shape)) {
         description[key] = {
           type: def.type,
-          optional: !!def.optional,
+          optional: isOptional(def),
+          immutable: !!def.isImmutable,
+          system: !!def.isSystem,
           description: def._description ?? "",
           version: def._version ?? "",
-          enum: getEnumValues(def),
-          refType: def.refType ?? void 0,
-          pii: def._pii ?? void 0
+          deprecated: def.deprecated ?? false,
+          deprecatedVersion: def.deprecatedVersion === void 0 ? null : def.deprecatedVersion,
+          enum: getEnumValues(def) ?? null,
+          refType: def.refType ?? null,
+          pii: !def._pii || def._pii.classification === "none" ? null : def._pii
         };
       }
       return {
@@ -1881,6 +2292,20 @@ function getSchemaForType(type) {
 function getAllSchemas() {
   return Array.from(globalSchemaRegistry.values());
 }
+function renderSchemaDescription(schema) {
+  const meta = schema.describe();
+  return {
+    title: `${meta.entityType} (v${meta.version})`,
+    fields: Object.entries(meta.shape).map(([name, def]) => ({
+      name,
+      type: def.type,
+      optional: def.optional,
+      description: def.description,
+      deprecated: def.deprecated,
+      pii: def.pii ? def.pii.classification : void 0
+    }))
+  };
+}
 
 // src/components.ts
 var componentSchemaRegistry = /* @__PURE__ */ new Map();
@@ -1906,6 +2331,7 @@ function getAllComponentSchemas() {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   FieldBuilder,
+  IsoLanguageCode,
   createComponentSchema,
   createSchema,
   field,
@@ -1913,13 +2339,23 @@ function getAllComponentSchemas() {
   getAllSchemas,
   getComponentSchema,
   getSchemaForType,
+  isExtensionSingleton,
+  isExtensionSubtag,
+  isIsoLanguageCode,
+  isPrivateUseSingleton,
+  isPrivateUseSubtag,
+  isRegionSubtag,
+  isScriptSubtag,
+  isVariantSubtag,
   isoCountryCodes,
   isoCurrencyCodes,
   registerComponentSchema,
+  renderSchemaDescription,
   validateCountryCode,
   validateCurrencyCode,
   validateDateTimeISO,
   validateEmail,
+  validateLanguage,
   validateName,
   validatePercentage,
   validatePhone,