@makehq/forman-schema 1.9.4 → 1.9.6

package/dist/index.cjs

@@ -524,6 +524,7 @@ function udtspecCollapse(field) {
 }
 
 // src/forman.ts
+var EMPTY_OPTION_DESCRIPTION = "Optional field, can be left empty.";
 var SchemaConversionError = class extends Error {
   /** Field that caused the error */
   field;
@@ -886,11 +887,10 @@ function handleSelectOrPathType(field, result, context) {
       const placeholder = field.options.placeholder;
       if (isObject(placeholder) && placeholder.nested) {
         (options ||= []).push({
-          value: null,
+          value: "",
           label: placeholder.label,
           nested: placeholder.nested
         });
-        result.type = [result.type, "null"];
       }
     }
     if (options?.some((option) => {
@@ -944,6 +944,19 @@ function handleSelectOrPathType(field, result, context) {
       result.enum = (options || []).map((option) => option.value);
     }
   }
+  if (!field.required) {
+    if (result.enum && !result.enum.includes("")) {
+      result.enum = ["", ...result.enum];
+    } else if (result.oneOf && !result.oneOf.some((entry) => isObject(entry) && entry.const === "")) {
+      result.oneOf = [{ title: "Empty", const: "" }, ...result.oneOf];
+    }
+    if (result.default === void 0) {
+      result.default = "";
+    }
+    if (!result.description) {
+      result.description = EMPTY_OPTION_DESCRIPTION;
+    }
+  }
   result = handleNestedWithDomain(field, nested, domain, result, context);
   if (field.rpc) result = processRpcDirective(field, result, context);
   return result;
@@ -1137,6 +1150,7 @@ async function validateFormanWithDomainsInternal(domains, options) {
         path: [],
         tail: [],
         strict: options?.strict === true,
+        domainAliases: options?.domainAliases ?? {},
         validateNestedFields: () => {
           throw new Error("Cannot validate nested fields without parent field.");
         },
@@ -1179,6 +1193,18 @@ async function validateFormanWithDomainsInternal(domains, options) {
       }
     }
   }
+  if (options?.strict) {
+    for (const domain of Object.keys(domains)) {
+      if (!domains[domain]) continue;
+      const root = roots[domain];
+      for (const key of Object.keys(domains[domain].values)) {
+        if (!root.seenFields.has(key)) {
+          root.seenFields.add(key);
+          errors.push({ domain, path: "", message: `Unknown field '${key}'.` });
+        }
+      }
+    }
+  }
   return {
     valid: errors.length === 0,
     errors,
@@ -1207,7 +1233,7 @@ async function validateFormanValue(value, field, context) {
       ]
     };
   }
-  if (value == null) {
+  if (value == null || value === "") {
     if (normalizedField.type === "select" && hasPlaceholderNested(normalizedField)) {
       return handleSelectType(value, normalizedField, context);
     }
@@ -1361,7 +1387,7 @@ async function handleCollectionType2(value, field, context) {
       errors.push(...result.errors);
     }
   }
-  if (context.strict) {
+  if (context.strict && context.path.length > 0) {
     for (const key of Object.keys(value)) {
       if (!seen.has(key)) {
         seen.add(key);
@@ -1687,7 +1713,7 @@ async function handleSelectType(value, field, context) {
         });
       }
     }
-  } else if (value == null && hasPlaceholderNested(field)) {
+  } else if ((value == null || value === "") && hasPlaceholderNested(field)) {
     const placeholder = field.options.placeholder;
     if (placeholder.label) {
       context.roots[context.domain].fieldStates.push({
@@ -1775,15 +1801,16 @@ async function handleNestedFields(nested, value, field, context) {
     }
     store = resolvedStore;
   }
-  if (store && domain && domain !== context.domain) {
-    if (!context.roots[domain]) {
+  const resolvedDomain = domain ? context.domainAliases[domain] ?? domain : domain;
+  if (store && resolvedDomain && resolvedDomain !== context.domain) {
+    if (!context.roots[resolvedDomain]) {
       errors.push({
         domain: context.domain,
         path: context.path.join("."),
-        message: `Unable to process nested fields: Domain '${domain}' not found.`
+        message: resolvedDomain !== domain ? `Unable to process nested fields: Resolved domain '${resolvedDomain}' (from alias '${domain}') not found.` : `Unable to process nested fields: Domain '${domain}' not found.`
       });
     } else {
-      const result = await context.roots[domain].validateFields(store, context);
+      const result = await context.roots[resolvedDomain].validateFields(store, context);
       errors.push(...result.errors);
     }
   } else if (store) {
@@ -1919,10 +1946,11 @@ function toFormanSchema(field) {
     case "string":
       const pathInfo = Object.getOwnPropertyDescriptor(field, "x-path");
       if (pathInfo) {
+        const help = field.description === EMPTY_OPTION_DESCRIPTION ? void 0 : noEmpty(field.description);
         return {
           type: pathInfo.value.type,
           label: noEmpty(field.title),
-          help: noEmpty(field.description),
+          help,
           options: {
             store: Object.getOwnPropertyDescriptor(field, "x-fetch")?.value,
             showRoot: pathInfo.value.showRoot,
@@ -1931,18 +1959,20 @@ function toFormanSchema(field) {
         };
       }
       if (field.enum) {
+        const help = field.description === EMPTY_OPTION_DESCRIPTION ? void 0 : noEmpty(field.description);
         return {
           type: "select",
           label: noEmpty(field.title),
-          help: noEmpty(field.description),
-          options: field.enum.map((value) => ({ value }))
+          help,
+          options: field.enum.filter((value) => value !== "").map((value) => ({ value }))
         };
       } else if (field.oneOf) {
+        const help = field.description === EMPTY_OPTION_DESCRIPTION ? void 0 : noEmpty(field.description);
         return {
           type: "select",
           label: noEmpty(field.title),
-          help: noEmpty(field.description),
-          options: field.oneOf.filter((value) => value).map((value) => ({ value: value.const }))
+          help,
+          options: field.oneOf.filter((value) => value && value.const !== "").map((value) => ({ value: value.const }))
         };
       }
       let textField = {

package/dist/index.d.cts

@@ -216,6 +216,8 @@ type FormanValidationOptions = {
     states?: boolean;
     /** Remote resource resolver */
     resolveRemote?(path: string, data: Record<string, unknown>): Promise<unknown>;
+    /** Maps domain names used in nested.domain to actual domain keys passed to validateFormanWithDomains */
+    domainAliases?: Record<string, string>;
 };
 
 /**

package/dist/index.d.ts

@@ -216,6 +216,8 @@ type FormanValidationOptions = {
     states?: boolean;
     /** Remote resource resolver */
     resolveRemote?(path: string, data: Record<string, unknown>): Promise<unknown>;
+    /** Maps domain names used in nested.domain to actual domain keys passed to validateFormanWithDomains */
+    domainAliases?: Record<string, string>;
 };
 
 /**

package/dist/index.js

@@ -495,6 +495,7 @@ function udtspecCollapse(field) {
 }
 
 // src/forman.ts
+var EMPTY_OPTION_DESCRIPTION = "Optional field, can be left empty.";
 var SchemaConversionError = class extends Error {
   /** Field that caused the error */
   field;
@@ -857,11 +858,10 @@ function handleSelectOrPathType(field, result, context) {
       const placeholder = field.options.placeholder;
       if (isObject(placeholder) && placeholder.nested) {
         (options ||= []).push({
-          value: null,
+          value: "",
           label: placeholder.label,
           nested: placeholder.nested
         });
-        result.type = [result.type, "null"];
       }
     }
     if (options?.some((option) => {
@@ -915,6 +915,19 @@ function handleSelectOrPathType(field, result, context) {
       result.enum = (options || []).map((option) => option.value);
     }
   }
+  if (!field.required) {
+    if (result.enum && !result.enum.includes("")) {
+      result.enum = ["", ...result.enum];
+    } else if (result.oneOf && !result.oneOf.some((entry) => isObject(entry) && entry.const === "")) {
+      result.oneOf = [{ title: "Empty", const: "" }, ...result.oneOf];
+    }
+    if (result.default === void 0) {
+      result.default = "";
+    }
+    if (!result.description) {
+      result.description = EMPTY_OPTION_DESCRIPTION;
+    }
+  }
   result = handleNestedWithDomain(field, nested, domain, result, context);
   if (field.rpc) result = processRpcDirective(field, result, context);
   return result;
@@ -1108,6 +1121,7 @@ async function validateFormanWithDomainsInternal(domains, options) {
         path: [],
         tail: [],
         strict: options?.strict === true,
+        domainAliases: options?.domainAliases ?? {},
         validateNestedFields: () => {
           throw new Error("Cannot validate nested fields without parent field.");
         },
@@ -1150,6 +1164,18 @@ async function validateFormanWithDomainsInternal(domains, options) {
       }
     }
   }
+  if (options?.strict) {
+    for (const domain of Object.keys(domains)) {
+      if (!domains[domain]) continue;
+      const root = roots[domain];
+      for (const key of Object.keys(domains[domain].values)) {
+        if (!root.seenFields.has(key)) {
+          root.seenFields.add(key);
+          errors.push({ domain, path: "", message: `Unknown field '${key}'.` });
+        }
+      }
+    }
+  }
   return {
     valid: errors.length === 0,
     errors,
@@ -1178,7 +1204,7 @@ async function validateFormanValue(value, field, context) {
       ]
     };
   }
-  if (value == null) {
+  if (value == null || value === "") {
     if (normalizedField.type === "select" && hasPlaceholderNested(normalizedField)) {
       return handleSelectType(value, normalizedField, context);
     }
@@ -1332,7 +1358,7 @@ async function handleCollectionType2(value, field, context) {
       errors.push(...result.errors);
     }
   }
-  if (context.strict) {
+  if (context.strict && context.path.length > 0) {
     for (const key of Object.keys(value)) {
       if (!seen.has(key)) {
         seen.add(key);
@@ -1658,7 +1684,7 @@ async function handleSelectType(value, field, context) {
         });
       }
     }
-  } else if (value == null && hasPlaceholderNested(field)) {
+  } else if ((value == null || value === "") && hasPlaceholderNested(field)) {
     const placeholder = field.options.placeholder;
     if (placeholder.label) {
       context.roots[context.domain].fieldStates.push({
@@ -1746,15 +1772,16 @@ async function handleNestedFields(nested, value, field, context) {
     }
     store = resolvedStore;
   }
-  if (store && domain && domain !== context.domain) {
-    if (!context.roots[domain]) {
+  const resolvedDomain = domain ? context.domainAliases[domain] ?? domain : domain;
+  if (store && resolvedDomain && resolvedDomain !== context.domain) {
+    if (!context.roots[resolvedDomain]) {
       errors.push({
         domain: context.domain,
         path: context.path.join("."),
-        message: `Unable to process nested fields: Domain '${domain}' not found.`
+        message: resolvedDomain !== domain ? `Unable to process nested fields: Resolved domain '${resolvedDomain}' (from alias '${domain}') not found.` : `Unable to process nested fields: Domain '${domain}' not found.`
       });
     } else {
-      const result = await context.roots[domain].validateFields(store, context);
+      const result = await context.roots[resolvedDomain].validateFields(store, context);
       errors.push(...result.errors);
     }
   } else if (store) {
@@ -1890,10 +1917,11 @@ function toFormanSchema(field) {
     case "string":
       const pathInfo = Object.getOwnPropertyDescriptor(field, "x-path");
       if (pathInfo) {
+        const help = field.description === EMPTY_OPTION_DESCRIPTION ? void 0 : noEmpty(field.description);
         return {
           type: pathInfo.value.type,
           label: noEmpty(field.title),
-          help: noEmpty(field.description),
+          help,
           options: {
             store: Object.getOwnPropertyDescriptor(field, "x-fetch")?.value,
             showRoot: pathInfo.value.showRoot,
@@ -1902,18 +1930,20 @@ function toFormanSchema(field) {
         };
       }
       if (field.enum) {
+        const help = field.description === EMPTY_OPTION_DESCRIPTION ? void 0 : noEmpty(field.description);
         return {
           type: "select",
           label: noEmpty(field.title),
-          help: noEmpty(field.description),
-          options: field.enum.map((value) => ({ value }))
+          help,
+          options: field.enum.filter((value) => value !== "").map((value) => ({ value }))
         };
       } else if (field.oneOf) {
+        const help = field.description === EMPTY_OPTION_DESCRIPTION ? void 0 : noEmpty(field.description);
         return {
           type: "select",
           label: noEmpty(field.title),
-          help: noEmpty(field.description),
-          options: field.oneOf.filter((value) => value).map((value) => ({ value: value.const }))
+          help,
+          options: field.oneOf.filter((value) => value && value.const !== "").map((value) => ({ value: value.const }))
         };
       }
       let textField = {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@makehq/forman-schema",
-    "version": "1.9.4",
+    "version": "1.9.6",
     "description": "Forman Schema Tools",
     "license": "MIT",
     "author": "Make",