@makehq/forman-schema 1.8.3 → 1.9.0

package/dist/index.cjs

@@ -98,6 +98,60 @@ function findValueInSelectOptions(field, value, optionsAndGroups) {
   const found = optionsAndGroups.find((option) => "value" in option && option.value === value);
   return found;
 }
+function pathToString(path) {
+  let result = "";
+  for (const key of path) {
+    if (typeof key === "number") {
+      result += `[${key}]`;
+    } else {
+      if (result.length > 0) {
+        result += ".";
+      }
+      if (key.includes("`")) {
+        throw new Error(`Invalid path key: backticks are not allowed in key "${key}"`);
+      }
+      result += key.includes(".") ? `\`${key}\`` : key;
+    }
+  }
+  return result;
+}
+function stringToPath(str) {
+  const path = [];
+  let i = 0;
+  while (i < str.length) {
+    if (str[i] === ".") {
+      i++;
+      if (i >= str.length) break;
+    }
+    if (str[i] === "[") {
+      const end = str.indexOf("]", i);
+      if (end === -1) {
+        throw new Error(`Invalid path: missing closing bracket in "${str}"`);
+      }
+      const num = Number(str.slice(i + 1, end));
+      if (!Number.isInteger(num) || num < 0) {
+        throw new Error(`Invalid path: non-numeric or negative index in "${str}"`);
+      }
+      path.push(num);
+      i = end + 1;
+    } else if (str[i] === "`") {
+      const end = str.indexOf("`", i + 1);
+      if (end === -1) {
+        throw new Error(`Invalid path: missing closing backtick in "${str}"`);
+      }
+      path.push(str.slice(i + 1, end));
+      i = end + 1;
+    } else {
+      let end = i;
+      while (end < str.length && str[end] !== "." && str[end] !== "[") {
+        end++;
+      }
+      path.push(str.slice(i, end));
+      i = end;
+    }
+  }
+  return path;
+}
 function buildRestoreStructure(items) {
   const result = {};
   for (const item of items) {
@@ -223,6 +277,248 @@ var IML_BINARY_FILTER_OPERATORS = [
 ];
 var IML_FILTER_OPERATORS = [...IML_UNARY_FILTER_OPERATORS, ...IML_BINARY_FILTER_OPERATORS];
 
+// src/composites/udttype.ts
+function udttypeExpand(field) {
+  field.type = "select";
+  field.options = {
+    store: [
+      {
+        label: "Array",
+        value: "array",
+        nested: [
+          {
+            name: "spec",
+            type: "collection",
+            label: "Array Item Specification",
+            spec: [
+              {
+                name: "type",
+                label: "Type",
+                type: "udttype",
+                required: true,
+                default: "text"
+              }
+            ],
+            mappable: false
+          },
+          {
+            name: "required",
+            label: "Required",
+            type: "boolean",
+            required: true,
+            default: false,
+            mappable: false
+          }
+        ]
+      },
+      {
+        label: "Collection",
+        value: "collection",
+        nested: [
+          {
+            name: "spec",
+            label: "Specification",
+            type: "udtspec"
+          },
+          {
+            name: "sequence",
+            label: "Preserve the order of object keys",
+            type: "boolean",
+            mappable: false
+          },
+          {
+            name: "required",
+            label: "Required",
+            type: "boolean",
+            required: true,
+            default: false,
+            mappable: false
+          }
+        ]
+      },
+      {
+        label: "Date",
+        value: "date",
+        nested: [
+          {
+            name: "required",
+            label: "Required",
+            type: "boolean",
+            required: true,
+            default: false,
+            mappable: false
+          }
+        ]
+      },
+      {
+        label: "Text",
+        value: "text",
+        nested: [
+          {
+            name: "default",
+            label: "Default value",
+            placeholder: "Enter default value",
+            type: "text"
+          },
+          {
+            name: "required",
+            label: "Required",
+            type: "boolean",
+            required: true,
+            default: false,
+            mappable: false
+          },
+          {
+            name: "multiline",
+            label: "Multi-line",
+            type: "boolean",
+            required: true,
+            default: false,
+            mappable: false
+          }
+        ]
+      },
+      {
+        label: "Number",
+        value: "number",
+        nested: [
+          {
+            name: "default",
+            label: "Default value",
+            placeholder: "Enter default value",
+            type: "number"
+          },
+          {
+            name: "required",
+            label: "Required",
+            type: "boolean",
+            required: true,
+            default: false,
+            mappable: false
+          }
+        ]
+      },
+      {
+        label: "Boolean",
+        value: "boolean",
+        nested: [
+          {
+            name: "default",
+            label: "Default value",
+            placeholder: "Enter default value",
+            type: "boolean",
+            mappable: false
+          },
+          {
+            name: "required",
+            label: "Required",
+            type: "boolean",
+            required: true,
+            default: false,
+            mappable: false
+          }
+        ]
+      },
+      {
+        label: "Binary Data",
+        value: "buffer",
+        nested: [
+          {
+            name: "required",
+            label: "Required",
+            type: "boolean",
+            required: true,
+            default: false,
+            mappable: false
+          },
+          {
+            name: "codepage",
+            label: "Codepage",
+            type: "text",
+            help: "Possible values: `binary`, `utf8`. Leave empty if you're not sure."
+          }
+        ]
+      }
+    ]
+  };
+  return field;
+}
+function udttypeExtractInner(schema) {
+  const { title, description, ...inner } = schema;
+  return inner;
+}
+function udttypeWrapRef(ref, field) {
+  return {
+    allOf: [{ $ref: ref }],
+    title: noEmpty(field.label),
+    description: noEmpty(field.help),
+    ...field.default !== "" && field.default != null ? { default: field.default } : {}
+  };
+}
+function udttypeCollapse(field) {
+  return {
+    type: "udttype",
+    label: noEmpty(field.title),
+    help: noEmpty(field.description),
+    ...field.default !== "" && field.default != null ? { default: field.default } : {}
+  };
+}
+
+// src/composites/udtspec.ts
+function udtspecExpand(field) {
+  field.type = "array";
+  field.spec = [
+    {
+      name: "name",
+      label: "Name",
+      placeholder: "Enter name",
+      type: "text",
+      required: true
+    },
+    {
+      name: "label",
+      label: "Label",
+      help: "Display name for better readability.",
+      type: "text",
+      advanced: true
+    },
+    {
+      name: "help",
+      label: "Description",
+      type: "text",
+      multiline: true,
+      required: false,
+      placeholder: "Enter description"
+    },
+    {
+      name: "type",
+      label: "Type",
+      type: "udttype",
+      required: true,
+      default: "text"
+    }
+  ];
+  return field;
+}
+function udtspecExtractInner(schema) {
+  return schema.items;
+}
+function udtspecWrapRef(ref, field) {
+  return {
+    type: "array",
+    title: noEmpty(field.label),
+    description: noEmpty(field.help),
+    items: { $ref: ref }
+  };
+}
+function udtspecCollapse(field) {
+  return {
+    type: "udtspec",
+    label: noEmpty(field.title),
+    help: noEmpty(field.description)
+  };
+}
+
 // src/forman.ts
 var SchemaConversionError = class extends Error {
   /** Field that caused the error */
@@ -269,6 +565,8 @@ var FORMAN_TYPE_MAP = {
   pkey: "string",
   port: "number",
   select: "string",
+  udttype: "string",
+  udtspec: "array",
   time: "string",
   timestamp: "string",
   timezone: "string",
@@ -298,14 +596,52 @@ function createDefaultContext() {
     tail: [],
     path: [],
     roots: {},
+    definitions: {},
     addConditionalFields: () => {
       throw new SchemaConversionError("Cannot serialize nested fields without parent field.");
     }
   };
 }
-function toJSONSchemaInternal(field, context = createDefaultContext()) {
+var compositeHandlers = {
+  udtspec: { expand: udtspecExpand, extractInner: udtspecExtractInner, wrapRef: udtspecWrapRef },
+  udttype: { expand: udttypeExpand, extractInner: udttypeExtractInner, wrapRef: udttypeWrapRef }
+};
+function toJSONSchemaInternal(field, context) {
   validateFormanField(field);
   const normalizedField = normalizeFormanFieldType(field);
+  const handler = compositeHandlers[normalizedField.type];
+  if (handler) {
+    const type = normalizedField.type;
+    const ref = `#/definitions/${type}`;
+    if (!context.definitions?.[type]) {
+      if (context.definitions) {
+        context.definitions[type] = {};
+      }
+      const expandField = { ...normalizedField };
+      delete expandField.label;
+      delete expandField.help;
+      const expanded = handler.expand(expandField);
+      const expandedResult = toJSONSchemaInternal(expanded, context);
+      const inner = handler.extractInner(expandedResult);
+      Object.defineProperty(inner, "x-composite", {
+        configurable: true,
+        enumerable: true,
+        writable: true,
+        value: type
+      });
+      if (context.definitions) {
+        context.definitions[type] = inner;
+      }
+    }
+    const wrapper = handler.wrapRef(ref, normalizedField);
+    Object.defineProperty(wrapper, "x-composite", {
+      configurable: true,
+      enumerable: true,
+      writable: true,
+      value: type
+    });
+    return wrapper;
+  }
   const result = {
     type: FORMAN_TYPE_MAP[normalizedField.type],
     title: noEmpty(normalizedField.label),
@@ -723,6 +1059,8 @@ var FORMAN_TYPE_MAP2 = {
   pkey: "string",
   port: "number",
   select: void 0,
+  udttype: "string",
+  udtspec: "array",
   time: "string",
   timestamp: "string",
   timezone: "string",
@@ -795,6 +1133,25 @@ async function validateFormanWithDomainsInternal(domains, options) {
       }
     );
     errors.push(...result.errors);
+    const restoreExtras = options?.states && domains[domain]?.restoreExtras;
+    if (restoreExtras) {
+      const fieldStateMap = new Map(
+        roots[domain].fieldStates.map(({ path, state }) => {
+          return [pathToString(path), state];
+        })
+      );
+      for (const [fieldPath, extra] of Object.entries(restoreExtras)) {
+        const state = fieldStateMap.get(fieldPath);
+        if (state) {
+          state.extra = extra;
+        } else {
+          roots[domain].fieldStates.push({
+            path: stringToPath(fieldPath),
+            state: { extra }
+          });
+        }
+      }
+    }
   }
   return {
     valid: errors.length === 0,
@@ -863,6 +1220,12 @@ async function validateFormanValue(value, field, context) {
       errors: []
     };
   }
+  if (normalizedField.type === "udttype") {
+    return validateFormanValue(value, udttypeExpand({ ...normalizedField }), context);
+  }
+  if (normalizedField.type === "udtspec") {
+    return validateFormanValue(value, udtspecExpand({ ...normalizedField }), context);
+  }
   switch (normalizedField.type) {
     case "collection":
       return handleCollectionType2(value, normalizedField, context);
@@ -1212,7 +1575,21 @@ async function handleSelectType(value, field, context) {
   let nested = field.nested ? field.nested : isObject(field.options) ? field.options.nested : void 0;
   if (typeof optionsOrGroups === "string") {
     try {
-      optionsOrGroups = await context.resolveRemote(optionsOrGroups, context);
+      const resolved = await context.resolveRemote(optionsOrGroups, context);
+      if (resolved == null || typeof resolved !== "object") {
+        return {
+          valid: false,
+          errors: [
+            ...errors,
+            {
+              domain: context.domain,
+              path: context.path.join("."),
+              message: `Remote resource ${optionsOrGroups} returned no data.`
+            }
+          ]
+        };
+      }
+      optionsOrGroups = Array.isArray(resolved) ? resolved : [resolved];
     } catch (error) {
       return {
         valid: false,
@@ -1322,7 +1699,12 @@ async function handleNestedFields(nested, value, field, context) {
     for (const item of store) {
       if (typeof item === "string") {
         try {
-          resolvedStore.push(...await context.resolveRemote(item, context));
+          const resolved = await context.resolveRemote(item, context);
+          if (Array.isArray(resolved)) {
+            resolvedStore.push(...resolved);
+          } else if (resolved && typeof resolved === "object") {
+            resolvedStore.push(resolved);
+          }
         } catch (error) {
           return {
             valid: false,
@@ -1430,6 +1812,9 @@ var JSON_PRIMITIVE_TYPE_MAP = {
   boolean: "boolean"
 };
 function toFormanSchema(field) {
+  const compositeType = Object.getOwnPropertyDescriptor(field, "x-composite")?.value;
+  if (compositeType === "udttype") return udttypeCollapse(field);
+  if (compositeType === "udtspec") return udtspecCollapse(field);
   switch (field.type) {
     case "object":
       if (!field.properties || !Object.entries(field.properties).length) {
@@ -1552,13 +1937,23 @@ function handleSearchDirective(formanField, directive) {
 
 // src/index.ts
 function toJSONSchema(field) {
-  return toJSONSchemaInternal(field);
+  const context = createDefaultContext();
+  const result = toJSONSchemaInternal(field, context);
+  if (Object.keys(context.definitions ?? {}).length > 0) {
+    Object.defineProperty(result, "definitions", {
+      configurable: true,
+      enumerable: true,
+      writable: true,
+      value: context.definitions
+    });
+  }
+  return result;
 }
 function validateFormanWithDomains(domains, options) {
   return validateFormanWithDomainsInternal(domains, options);
 }
-function validateForman(values, schema, options) {
-  return validateFormanWithDomains({ default: { values, schema } }, options);
+function validateForman(values, schema, options, restoreExtras) {
+  return validateFormanWithDomains({ default: { values, schema, restoreExtras } }, options);
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/index.d.cts

@@ -205,6 +205,7 @@ type FormanSchemaFieldState = {
     label?: string;
     path?: Array<string>;
     data?: Record<string, unknown>;
+    extra?: Record<string, unknown>;
     nested?: Record<string, FormanSchemaFieldState>;
     items?: Record<string, FormanSchemaFieldState>[];
 };
@@ -239,14 +240,19 @@ declare function toJSONSchema(field: FormanSchemaField): JSONSchema7;
 declare function validateFormanWithDomains(domains: Record<string, {
     values: Record<string, unknown>;
     schema: FormanSchemaField[];
+    /** Extra values injected into restore states, keyed by string path (dot notation, `[index]`, backtick-escaping). */
+    restoreExtras?: Record<string, Record<string, unknown>>;
 }>, options?: FormanValidationOptions): Promise<FormanValidationResult>;
 /**
  * Validates a simple Forman values against a schema
  * @param values The values to validate
  * @param schema The schema to validate against
  * @param options The validation options
+ * @param restoreExtras Values to be injected into restore objects of particular fields.
+ *   Keyed by string path using dot notation for nested keys, `[index]` for array indices,
+ *   and backtick-escaping for keys containing dots (e.g. `"a.b[0].c"`, `` "`dotted.key`.child" ``).
  * @returns The validation result
  */
-declare function validateForman(values: Record<string, unknown>, schema: FormanSchemaField[], options?: FormanValidationOptions): Promise<FormanValidationResult>;
+declare function validateForman(values: Record<string, unknown>, schema: FormanSchemaField[], options?: FormanValidationOptions, restoreExtras?: Record<string, Record<string, unknown>>): Promise<FormanValidationResult>;
 
 export { type FormanSchemaDirectoryOption, type FormanSchemaExtendedNested, type FormanSchemaExtendedOptions, type FormanSchemaField, type FormanSchemaFieldType, type FormanSchemaNested, type FormanSchemaOption, type FormanSchemaOptionGroup, type FormanSchemaPathExtendedOptions, type FormanSchemaRPCButton, type FormanSchemaValue, toFormanSchema, toJSONSchema, validateForman, validateFormanWithDomains };

package/dist/index.d.ts

@@ -205,6 +205,7 @@ type FormanSchemaFieldState = {
     label?: string;
     path?: Array<string>;
     data?: Record<string, unknown>;
+    extra?: Record<string, unknown>;
     nested?: Record<string, FormanSchemaFieldState>;
     items?: Record<string, FormanSchemaFieldState>[];
 };
@@ -239,14 +240,19 @@ declare function toJSONSchema(field: FormanSchemaField): JSONSchema7;
 declare function validateFormanWithDomains(domains: Record<string, {
     values: Record<string, unknown>;
     schema: FormanSchemaField[];
+    /** Extra values injected into restore states, keyed by string path (dot notation, `[index]`, backtick-escaping). */
+    restoreExtras?: Record<string, Record<string, unknown>>;
 }>, options?: FormanValidationOptions): Promise<FormanValidationResult>;
 /**
  * Validates a simple Forman values against a schema
  * @param values The values to validate
  * @param schema The schema to validate against
  * @param options The validation options
+ * @param restoreExtras Values to be injected into restore objects of particular fields.
+ *   Keyed by string path using dot notation for nested keys, `[index]` for array indices,
+ *   and backtick-escaping for keys containing dots (e.g. `"a.b[0].c"`, `` "`dotted.key`.child" ``).
  * @returns The validation result
  */
-declare function validateForman(values: Record<string, unknown>, schema: FormanSchemaField[], options?: FormanValidationOptions): Promise<FormanValidationResult>;
+declare function validateForman(values: Record<string, unknown>, schema: FormanSchemaField[], options?: FormanValidationOptions, restoreExtras?: Record<string, Record<string, unknown>>): Promise<FormanValidationResult>;
 
 export { type FormanSchemaDirectoryOption, type FormanSchemaExtendedNested, type FormanSchemaExtendedOptions, type FormanSchemaField, type FormanSchemaFieldType, type FormanSchemaNested, type FormanSchemaOption, type FormanSchemaOptionGroup, type FormanSchemaPathExtendedOptions, type FormanSchemaRPCButton, type FormanSchemaValue, toFormanSchema, toJSONSchema, validateForman, validateFormanWithDomains };

package/dist/index.js

@@ -69,6 +69,60 @@ function findValueInSelectOptions(field, value, optionsAndGroups) {
   const found = optionsAndGroups.find((option) => "value" in option && option.value === value);
   return found;
 }
+function pathToString(path) {
+  let result = "";
+  for (const key of path) {
+    if (typeof key === "number") {
+      result += `[${key}]`;
+    } else {
+      if (result.length > 0) {
+        result += ".";
+      }
+      if (key.includes("`")) {
+        throw new Error(`Invalid path key: backticks are not allowed in key "${key}"`);
+      }
+      result += key.includes(".") ? `\`${key}\`` : key;
+    }
+  }
+  return result;
+}
+function stringToPath(str) {
+  const path = [];
+  let i = 0;
+  while (i < str.length) {
+    if (str[i] === ".") {
+      i++;
+      if (i >= str.length) break;
+    }
+    if (str[i] === "[") {
+      const end = str.indexOf("]", i);
+      if (end === -1) {
+        throw new Error(`Invalid path: missing closing bracket in "${str}"`);
+      }
+      const num = Number(str.slice(i + 1, end));
+      if (!Number.isInteger(num) || num < 0) {
+        throw new Error(`Invalid path: non-numeric or negative index in "${str}"`);
+      }
+      path.push(num);
+      i = end + 1;
+    } else if (str[i] === "`") {
+      const end = str.indexOf("`", i + 1);
+      if (end === -1) {
+        throw new Error(`Invalid path: missing closing backtick in "${str}"`);
+      }
+      path.push(str.slice(i + 1, end));
+      i = end + 1;
+    } else {
+      let end = i;
+      while (end < str.length && str[end] !== "." && str[end] !== "[") {
+        end++;
+      }
+      path.push(str.slice(i, end));
+      i = end;
+    }
+  }
+  return path;
+}
 function buildRestoreStructure(items) {
   const result = {};
   for (const item of items) {
@@ -194,6 +248,248 @@ var IML_BINARY_FILTER_OPERATORS = [
 ];
 var IML_FILTER_OPERATORS = [...IML_UNARY_FILTER_OPERATORS, ...IML_BINARY_FILTER_OPERATORS];
 
+// src/composites/udttype.ts
+function udttypeExpand(field) {
+  field.type = "select";
+  field.options = {
+    store: [
+      {
+        label: "Array",
+        value: "array",
+        nested: [
+          {
+            name: "spec",
+            type: "collection",
+            label: "Array Item Specification",
+            spec: [
+              {
+                name: "type",
+                label: "Type",
+                type: "udttype",
+                required: true,
+                default: "text"
+              }
+            ],
+            mappable: false
+          },
+          {
+            name: "required",
+            label: "Required",
+            type: "boolean",
+            required: true,
+            default: false,
+            mappable: false
+          }
+        ]
+      },
+      {
+        label: "Collection",
+        value: "collection",
+        nested: [
+          {
+            name: "spec",
+            label: "Specification",
+            type: "udtspec"
+          },
+          {
+            name: "sequence",
+            label: "Preserve the order of object keys",
+            type: "boolean",
+            mappable: false
+          },
+          {
+            name: "required",
+            label: "Required",
+            type: "boolean",
+            required: true,
+            default: false,
+            mappable: false
+          }
+        ]
+      },
+      {
+        label: "Date",
+        value: "date",
+        nested: [
+          {
+            name: "required",
+            label: "Required",
+            type: "boolean",
+            required: true,
+            default: false,
+            mappable: false
+          }
+        ]
+      },
+      {
+        label: "Text",
+        value: "text",
+        nested: [
+          {
+            name: "default",
+            label: "Default value",
+            placeholder: "Enter default value",
+            type: "text"
+          },
+          {
+            name: "required",
+            label: "Required",
+            type: "boolean",
+            required: true,
+            default: false,
+            mappable: false
+          },
+          {
+            name: "multiline",
+            label: "Multi-line",
+            type: "boolean",
+            required: true,
+            default: false,
+            mappable: false
+          }
+        ]
+      },
+      {
+        label: "Number",
+        value: "number",
+        nested: [
+          {
+            name: "default",
+            label: "Default value",
+            placeholder: "Enter default value",
+            type: "number"
+          },
+          {
+            name: "required",
+            label: "Required",
+            type: "boolean",
+            required: true,
+            default: false,
+            mappable: false
+          }
+        ]
+      },
+      {
+        label: "Boolean",
+        value: "boolean",
+        nested: [
+          {
+            name: "default",
+            label: "Default value",
+            placeholder: "Enter default value",
+            type: "boolean",
+            mappable: false
+          },
+          {
+            name: "required",
+            label: "Required",
+            type: "boolean",
+            required: true,
+            default: false,
+            mappable: false
+          }
+        ]
+      },
+      {
+        label: "Binary Data",
+        value: "buffer",
+        nested: [
+          {
+            name: "required",
+            label: "Required",
+            type: "boolean",
+            required: true,
+            default: false,
+            mappable: false
+          },
+          {
+            name: "codepage",
+            label: "Codepage",
+            type: "text",
+            help: "Possible values: `binary`, `utf8`. Leave empty if you're not sure."
+          }
+        ]
+      }
+    ]
+  };
+  return field;
+}
+function udttypeExtractInner(schema) {
+  const { title, description, ...inner } = schema;
+  return inner;
+}
+function udttypeWrapRef(ref, field) {
+  return {
+    allOf: [{ $ref: ref }],
+    title: noEmpty(field.label),
+    description: noEmpty(field.help),
+    ...field.default !== "" && field.default != null ? { default: field.default } : {}
+  };
+}
+function udttypeCollapse(field) {
+  return {
+    type: "udttype",
+    label: noEmpty(field.title),
+    help: noEmpty(field.description),
+    ...field.default !== "" && field.default != null ? { default: field.default } : {}
+  };
+}
+
+// src/composites/udtspec.ts
+function udtspecExpand(field) {
+  field.type = "array";
+  field.spec = [
+    {
+      name: "name",
+      label: "Name",
+      placeholder: "Enter name",
+      type: "text",
+      required: true
+    },
+    {
+      name: "label",
+      label: "Label",
+      help: "Display name for better readability.",
+      type: "text",
+      advanced: true
+    },
+    {
+      name: "help",
+      label: "Description",
+      type: "text",
+      multiline: true,
+      required: false,
+      placeholder: "Enter description"
+    },
+    {
+      name: "type",
+      label: "Type",
+      type: "udttype",
+      required: true,
+      default: "text"
+    }
+  ];
+  return field;
+}
+function udtspecExtractInner(schema) {
+  return schema.items;
+}
+function udtspecWrapRef(ref, field) {
+  return {
+    type: "array",
+    title: noEmpty(field.label),
+    description: noEmpty(field.help),
+    items: { $ref: ref }
+  };
+}
+function udtspecCollapse(field) {
+  return {
+    type: "udtspec",
+    label: noEmpty(field.title),
+    help: noEmpty(field.description)
+  };
+}
+
 // src/forman.ts
 var SchemaConversionError = class extends Error {
   /** Field that caused the error */
@@ -240,6 +536,8 @@ var FORMAN_TYPE_MAP = {
   pkey: "string",
   port: "number",
   select: "string",
+  udttype: "string",
+  udtspec: "array",
   time: "string",
   timestamp: "string",
   timezone: "string",
@@ -269,14 +567,52 @@ function createDefaultContext() {
     tail: [],
     path: [],
     roots: {},
+    definitions: {},
     addConditionalFields: () => {
       throw new SchemaConversionError("Cannot serialize nested fields without parent field.");
     }
   };
 }
-function toJSONSchemaInternal(field, context = createDefaultContext()) {
+var compositeHandlers = {
+  udtspec: { expand: udtspecExpand, extractInner: udtspecExtractInner, wrapRef: udtspecWrapRef },
+  udttype: { expand: udttypeExpand, extractInner: udttypeExtractInner, wrapRef: udttypeWrapRef }
+};
+function toJSONSchemaInternal(field, context) {
   validateFormanField(field);
   const normalizedField = normalizeFormanFieldType(field);
+  const handler = compositeHandlers[normalizedField.type];
+  if (handler) {
+    const type = normalizedField.type;
+    const ref = `#/definitions/${type}`;
+    if (!context.definitions?.[type]) {
+      if (context.definitions) {
+        context.definitions[type] = {};
+      }
+      const expandField = { ...normalizedField };
+      delete expandField.label;
+      delete expandField.help;
+      const expanded = handler.expand(expandField);
+      const expandedResult = toJSONSchemaInternal(expanded, context);
+      const inner = handler.extractInner(expandedResult);
+      Object.defineProperty(inner, "x-composite", {
+        configurable: true,
+        enumerable: true,
+        writable: true,
+        value: type
+      });
+      if (context.definitions) {
+        context.definitions[type] = inner;
+      }
+    }
+    const wrapper = handler.wrapRef(ref, normalizedField);
+    Object.defineProperty(wrapper, "x-composite", {
+      configurable: true,
+      enumerable: true,
+      writable: true,
+      value: type
+    });
+    return wrapper;
+  }
   const result = {
     type: FORMAN_TYPE_MAP[normalizedField.type],
     title: noEmpty(normalizedField.label),
@@ -694,6 +1030,8 @@ var FORMAN_TYPE_MAP2 = {
   pkey: "string",
   port: "number",
   select: void 0,
+  udttype: "string",
+  udtspec: "array",
   time: "string",
   timestamp: "string",
   timezone: "string",
@@ -766,6 +1104,25 @@ async function validateFormanWithDomainsInternal(domains, options) {
       }
     );
     errors.push(...result.errors);
+    const restoreExtras = options?.states && domains[domain]?.restoreExtras;
+    if (restoreExtras) {
+      const fieldStateMap = new Map(
+        roots[domain].fieldStates.map(({ path, state }) => {
+          return [pathToString(path), state];
+        })
+      );
+      for (const [fieldPath, extra] of Object.entries(restoreExtras)) {
+        const state = fieldStateMap.get(fieldPath);
+        if (state) {
+          state.extra = extra;
+        } else {
+          roots[domain].fieldStates.push({
+            path: stringToPath(fieldPath),
+            state: { extra }
+          });
+        }
+      }
+    }
   }
   return {
     valid: errors.length === 0,
@@ -834,6 +1191,12 @@ async function validateFormanValue(value, field, context) {
       errors: []
     };
   }
+  if (normalizedField.type === "udttype") {
+    return validateFormanValue(value, udttypeExpand({ ...normalizedField }), context);
+  }
+  if (normalizedField.type === "udtspec") {
+    return validateFormanValue(value, udtspecExpand({ ...normalizedField }), context);
+  }
   switch (normalizedField.type) {
     case "collection":
       return handleCollectionType2(value, normalizedField, context);
@@ -1183,7 +1546,21 @@ async function handleSelectType(value, field, context) {
   let nested = field.nested ? field.nested : isObject(field.options) ? field.options.nested : void 0;
   if (typeof optionsOrGroups === "string") {
     try {
-      optionsOrGroups = await context.resolveRemote(optionsOrGroups, context);
+      const resolved = await context.resolveRemote(optionsOrGroups, context);
+      if (resolved == null || typeof resolved !== "object") {
+        return {
+          valid: false,
+          errors: [
+            ...errors,
+            {
+              domain: context.domain,
+              path: context.path.join("."),
+              message: `Remote resource ${optionsOrGroups} returned no data.`
+            }
+          ]
+        };
+      }
+      optionsOrGroups = Array.isArray(resolved) ? resolved : [resolved];
     } catch (error) {
       return {
         valid: false,
@@ -1293,7 +1670,12 @@ async function handleNestedFields(nested, value, field, context) {
     for (const item of store) {
       if (typeof item === "string") {
         try {
-          resolvedStore.push(...await context.resolveRemote(item, context));
+          const resolved = await context.resolveRemote(item, context);
+          if (Array.isArray(resolved)) {
+            resolvedStore.push(...resolved);
+          } else if (resolved && typeof resolved === "object") {
+            resolvedStore.push(resolved);
+          }
         } catch (error) {
           return {
             valid: false,
@@ -1401,6 +1783,9 @@ var JSON_PRIMITIVE_TYPE_MAP = {
   boolean: "boolean"
 };
 function toFormanSchema(field) {
+  const compositeType = Object.getOwnPropertyDescriptor(field, "x-composite")?.value;
+  if (compositeType === "udttype") return udttypeCollapse(field);
+  if (compositeType === "udtspec") return udtspecCollapse(field);
   switch (field.type) {
     case "object":
       if (!field.properties || !Object.entries(field.properties).length) {
@@ -1523,13 +1908,23 @@ function handleSearchDirective(formanField, directive) {
 
 // src/index.ts
 function toJSONSchema(field) {
-  return toJSONSchemaInternal(field);
+  const context = createDefaultContext();
+  const result = toJSONSchemaInternal(field, context);
+  if (Object.keys(context.definitions ?? {}).length > 0) {
+    Object.defineProperty(result, "definitions", {
+      configurable: true,
+      enumerable: true,
+      writable: true,
+      value: context.definitions
+    });
+  }
+  return result;
 }
 function validateFormanWithDomains(domains, options) {
   return validateFormanWithDomainsInternal(domains, options);
 }
-function validateForman(values, schema, options) {
-  return validateFormanWithDomains({ default: { values, schema } }, options);
+function validateForman(values, schema, options, restoreExtras) {
+  return validateFormanWithDomains({ default: { values, schema, restoreExtras } }, options);
 }
 export {
   toFormanSchema,

package/package.json

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