@makehq/forman-schema 1.8.2 → 1.8.4

package/dist/index.cjs

@@ -223,6 +223,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 +511,8 @@ var FORMAN_TYPE_MAP = {
   pkey: "string",
   port: "number",
   select: "string",
+  udttype: "string",
+  udtspec: "array",
   time: "string",
   timestamp: "string",
   timezone: "string",
@@ -298,14 +542,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),
@@ -412,31 +694,92 @@ function handleArrayType(field, result, context) {
   return result;
 }
 function handleFilterType(field, result, context) {
-  const filterItems = {
+  const operandOptions = isObject(field.options) ? field.options.store : field.options;
+  const operandSchema = {
+    title: "Operand A",
+    description: "The first operand of the filter."
+  };
+  if (Array.isArray(operandOptions)) {
+    operandSchema.type = "string";
+    operandSchema.oneOf = operandOptions.flatMap((optionOrGroup) => {
+      if (isOptionGroup(optionOrGroup)) {
+        return optionOrGroup.options.map((option) => ({
+          title: `${optionOrGroup.label}: ${option.label || option.value}`,
+          const: option.value
+        }));
+      }
+      return {
+        title: optionOrGroup.label || String(optionOrGroup.value),
+        const: optionOrGroup.value
+      };
+    });
+  } else if (typeof operandOptions === "string") {
+    operandSchema.type = "string";
+    Object.defineProperty(operandSchema, "x-fetch", {
+      configurable: true,
+      enumerable: true,
+      writable: true,
+      value: appendQueryString(operandOptions, context.domain, context.tail)
+    });
+  } else {
+    operandSchema.type = IML_FILTER_ENTRY_TYPES;
+  }
+  const operatorOptions = isObject(field.options) ? field.options.operators : void 0;
+  const operatorSchema = {
+    title: "Operator",
+    description: "The operator of the filter."
+  };
+  if (Array.isArray(operatorOptions)) {
+    operatorSchema.type = "string";
+    operatorSchema.oneOf = operatorOptions.flatMap((optionOrGroup) => {
+      if (isOptionGroup(optionOrGroup)) {
+        return optionOrGroup.options.map((option) => ({
+          title: `${optionOrGroup.label}: ${option.label || option.value}`,
+          const: option.value
+        }));
+      }
+      return {
+        title: optionOrGroup.label || String(optionOrGroup.value),
+        const: optionOrGroup.value
+      };
+    });
+  } else {
+    operatorSchema.enum = IML_BINARY_FILTER_OPERATORS;
+  }
+  const filterDefinition = {
     oneOf: [
       {
         type: "object",
         properties: {
-          a: { type: IML_FILTER_ENTRY_TYPES },
-          o: { enum: IML_UNARY_FILTER_OPERATORS }
-        },
-        required: ["a", "o"]
-      },
-      {
-        type: "object",
-        properties: {
-          a: { type: IML_FILTER_ENTRY_TYPES },
-          b: { type: IML_FILTER_ENTRY_TYPES },
-          o: { enum: IML_BINARY_FILTER_OPERATORS }
+          a: operandSchema,
+          o: operatorSchema,
+          b: {
+            title: "Operand B",
+            description: "The second operand of the filter.",
+            type: IML_FILTER_ENTRY_TYPES
+          }
         },
         required: ["a", "b", "o"]
       }
     ]
   };
+  if (!operatorOptions) {
+    filterDefinition.oneOf?.push({
+      type: "object",
+      properties: {
+        a: operandSchema,
+        o: {
+          ...operatorSchema,
+          enum: IML_UNARY_FILTER_OPERATORS
+        }
+      },
+      required: ["a", "o"]
+    });
+  }
   const logic = field.logic ?? "default";
-  result.items = ["and", "or"].includes(logic) ? filterItems : {
+  result.items = ["and", "or"].includes(logic) ? filterDefinition : {
     type: "array",
-    items: filterItems
+    items: filterDefinition
   };
   Object.defineProperty(result, "x-filter", {
     configurable: true,
@@ -462,9 +805,7 @@ function handleSelectOrPathType(field, result, context) {
       }
     });
   }
-  const nested = isObject(field.options) ? isObject(field.options.nested) ? field.options.nested.store : field.options.nested : void 0;
-  const nestedContainsStrings = Array.isArray(nested) && nested.some((item) => typeof item === "string");
-  const domain = isObject(field.options) ? isObject(field.options.nested) && field.options.nested.domain ? field.options.nested.domain : void 0 : void 0;
+  const { nested, domain } = extractNestedAndDomain(field);
   if (typeof optionsOrGroups === "string") {
     Object.defineProperty(result, "x-fetch", {
       configurable: true,
@@ -533,46 +874,7 @@ function handleSelectOrPathType(field, result, context) {
       result.enum = (options || []).map((option) => option.value);
     }
   }
-  if (nested && domain && domain !== context.domain) {
-    const normalizedNested = typeof nested === "string" ? [nested] : nested;
-    let root = context.roots[domain];
-    if (!root) {
-      const buffer = [];
-      root = context.roots[domain] = {
-        buffer,
-        addFields: (nested2, tail) => {
-          buffer.push(...nested2.map((field2) => ({ field: field2, tail })));
-        }
-      };
-    }
-    root.addFields(normalizedNested, [...context.tail, field.name]);
-  } else if (nested) {
-    Object.defineProperty(result, "x-nested", {
-      configurable: true,
-      enumerable: true,
-      writable: true,
-      value: typeof nested === "string" ? { $ref: appendQueryString(nested, context.domain, [...context.tail, field.name]) } : nestedContainsStrings ? {
-        type: "object",
-        allOf: nested.map(
-          (item) => typeof item === "string" ? { $ref: appendQueryString(item, context.domain, [...context.tail, field.name]) } : toJSONSchemaInternal(
-            { type: "collection", spec: [item] },
-            {
-              ...context,
-              domain: domain || context.domain,
-              tail: [...context.tail, field.name]
-            }
-          )
-        )
-      } : toJSONSchemaInternal(
-        { type: "collection", spec: nested },
-        {
-          ...context,
-          domain: domain || context.domain,
-          tail: [...context.tail, field.name]
-        }
-      )
-    });
-  }
+  result = handleNestedWithDomain(field, nested, domain, result, context);
   if (field.rpc) result = processRpcDirective(field, result, context);
   return result;
 }
@@ -595,6 +897,10 @@ function handlePrimitiveType(field, result, context) {
     }
   }
   if (field.rpc) result = processRpcDirective(field, result, context);
+  if (field.nested) {
+    const { nested, domain } = extractNestedAndDomain(field);
+    result = handleNestedWithDomain(field, nested, domain, result, context);
+  }
   return result;
 }
 function processRpcDirective(field, result, context) {
@@ -611,6 +917,60 @@ function processRpcDirective(field, result, context) {
   });
   return result;
 }
+function extractNestedAndDomain(field) {
+  const nested = isObject(field.options) ? isObject(field.options.nested) ? field.options.nested.store : field.options.nested : isObject(field.nested) ? field.nested.store : field.nested;
+  const domain = isObject(field.options) ? isObject(field.options.nested) && field.options.nested.domain ? field.options.nested.domain : void 0 : isObject(field.nested) && field.nested.domain ? field.nested.domain : void 0;
+  return { nested, domain };
+}
+function handleNestedWithDomain(field, nested, domain, result, context) {
+  if (!nested) return result;
+  if (domain && domain !== context.domain) {
+    const normalizedNested = typeof nested === "string" ? [nested] : nested;
+    let root = context.roots[domain];
+    if (!root) {
+      const buffer = [];
+      root = context.roots[domain] = {
+        buffer,
+        addFields: (nested2, tail) => {
+          buffer.push(...nested2.map((field2) => ({ field: field2, tail })));
+        }
+      };
+    }
+    root.addFields(normalizedNested, [...context.tail, field.name]);
+    return result;
+  }
+  return processNestedDirective(field, nested, domain, result, context);
+}
+function processNestedDirective(field, nested, domain, result, context) {
+  if (!nested) return result;
+  const nestedContainsStrings = Array.isArray(nested) && nested.some((item) => typeof item === "string");
+  Object.defineProperty(result, "x-nested", {
+    configurable: true,
+    enumerable: true,
+    writable: true,
+    value: typeof nested === "string" ? { $ref: appendQueryString(nested, context.domain, [...context.tail, field.name]) } : nestedContainsStrings ? {
+      type: "object",
+      allOf: nested.map(
+        (item) => typeof item === "string" ? { $ref: appendQueryString(item, context.domain, [...context.tail, field.name]) } : toJSONSchemaInternal(
+          { type: "collection", spec: [item] },
+          {
+            ...context,
+            domain: domain || context.domain,
+            tail: [...context.tail, field.name]
+          }
+        )
+      )
+    } : toJSONSchemaInternal(
+      { type: "collection", spec: nested },
+      {
+        ...context,
+        domain: domain || context.domain,
+        tail: [...context.tail, field.name]
+      }
+    )
+  });
+  return result;
+}
 
 // src/validator.ts
 var FORMAN_TYPE_MAP2 = {
@@ -645,6 +1005,8 @@ var FORMAN_TYPE_MAP2 = {
   pkey: "string",
   port: "number",
   select: void 0,
+  udttype: "string",
+  udtspec: "array",
   time: "string",
   timestamp: "string",
   timezone: "string",
@@ -785,6 +1147,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);
@@ -932,24 +1300,40 @@ async function handleArrayType2(value, field, context) {
   };
 }
 async function handleFilterType2(value, field, context) {
+  const operandOptions = isObject(field.options) ? field.options.store : field.options;
+  const operandSpec = {
+    name: "a",
+    type: "any",
+    required: true
+  };
+  if (Array.isArray(operandOptions)) {
+    operandSpec.type = "select";
+    operandSpec.options = operandOptions;
+  }
+  const operatorOptions = isObject(field.options) ? field.options.operators : void 0;
+  const operatorSpec = {
+    name: "o",
+    type: "any",
+    required: true
+  };
+  if (Array.isArray(operatorOptions)) {
+    operatorSpec.type = "select";
+    operatorSpec.grouped = true;
+    operatorSpec.options = operatorOptions;
+  } else {
+    operatorSpec.type = "text";
+    operatorSpec.validate = {
+      enum: IML_FILTER_OPERATORS
+    };
+  }
   const filterEntry = {
     type: "collection",
     spec: [
-      {
-        name: "a",
-        type: "any",
-        required: true
-      },
+      operandSpec,
+      operatorSpec,
       {
         name: "b",
         type: "any"
-      },
-      {
-        name: "o",
-        type: "text",
-        validate: {
-          enum: IML_FILTER_OPERATORS
-        }
       }
     ]
   };
@@ -1118,7 +1502,18 @@ 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,
@@ -1228,7 +1623,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,
@@ -1336,6 +1736,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) {
@@ -1458,7 +1861,17 @@ 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);

package/dist/index.d.cts

@@ -145,6 +145,10 @@ type FormanSchemaOptionGroup = {
     /** Group options */
     options: FormanSchemaOption[];
 };
+/**
+ * Helper type for store of select, where options can be either plain options, or groups
+ */
+type FormanSchemaSelectOptionsStore = (FormanSchemaOption | FormanSchemaOptionGroup)[];
 /**
  * Extended options for a select field
  */
@@ -162,6 +166,8 @@ type FormanSchemaExtendedOptions = {
         label: string;
         nested?: FormanSchemaNested;
     };
+    /** Definition of field operators, applicable on Filter fields. */
+    operators?: FormanSchemaSelectOptionsStore;
 };
 /**
  * Nested fields

package/dist/index.d.ts

@@ -145,6 +145,10 @@ type FormanSchemaOptionGroup = {
     /** Group options */
     options: FormanSchemaOption[];
 };
+/**
+ * Helper type for store of select, where options can be either plain options, or groups
+ */
+type FormanSchemaSelectOptionsStore = (FormanSchemaOption | FormanSchemaOptionGroup)[];
 /**
  * Extended options for a select field
  */
@@ -162,6 +166,8 @@ type FormanSchemaExtendedOptions = {
         label: string;
         nested?: FormanSchemaNested;
     };
+    /** Definition of field operators, applicable on Filter fields. */
+    operators?: FormanSchemaSelectOptionsStore;
 };
 /**
  * Nested fields

package/dist/index.js

@@ -194,6 +194,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 +482,8 @@ var FORMAN_TYPE_MAP = {
   pkey: "string",
   port: "number",
   select: "string",
+  udttype: "string",
+  udtspec: "array",
   time: "string",
   timestamp: "string",
   timezone: "string",
@@ -269,14 +513,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),
@@ -383,31 +665,92 @@ function handleArrayType(field, result, context) {
   return result;
 }
 function handleFilterType(field, result, context) {
-  const filterItems = {
+  const operandOptions = isObject(field.options) ? field.options.store : field.options;
+  const operandSchema = {
+    title: "Operand A",
+    description: "The first operand of the filter."
+  };
+  if (Array.isArray(operandOptions)) {
+    operandSchema.type = "string";
+    operandSchema.oneOf = operandOptions.flatMap((optionOrGroup) => {
+      if (isOptionGroup(optionOrGroup)) {
+        return optionOrGroup.options.map((option) => ({
+          title: `${optionOrGroup.label}: ${option.label || option.value}`,
+          const: option.value
+        }));
+      }
+      return {
+        title: optionOrGroup.label || String(optionOrGroup.value),
+        const: optionOrGroup.value
+      };
+    });
+  } else if (typeof operandOptions === "string") {
+    operandSchema.type = "string";
+    Object.defineProperty(operandSchema, "x-fetch", {
+      configurable: true,
+      enumerable: true,
+      writable: true,
+      value: appendQueryString(operandOptions, context.domain, context.tail)
+    });
+  } else {
+    operandSchema.type = IML_FILTER_ENTRY_TYPES;
+  }
+  const operatorOptions = isObject(field.options) ? field.options.operators : void 0;
+  const operatorSchema = {
+    title: "Operator",
+    description: "The operator of the filter."
+  };
+  if (Array.isArray(operatorOptions)) {
+    operatorSchema.type = "string";
+    operatorSchema.oneOf = operatorOptions.flatMap((optionOrGroup) => {
+      if (isOptionGroup(optionOrGroup)) {
+        return optionOrGroup.options.map((option) => ({
+          title: `${optionOrGroup.label}: ${option.label || option.value}`,
+          const: option.value
+        }));
+      }
+      return {
+        title: optionOrGroup.label || String(optionOrGroup.value),
+        const: optionOrGroup.value
+      };
+    });
+  } else {
+    operatorSchema.enum = IML_BINARY_FILTER_OPERATORS;
+  }
+  const filterDefinition = {
     oneOf: [
       {
         type: "object",
         properties: {
-          a: { type: IML_FILTER_ENTRY_TYPES },
-          o: { enum: IML_UNARY_FILTER_OPERATORS }
-        },
-        required: ["a", "o"]
-      },
-      {
-        type: "object",
-        properties: {
-          a: { type: IML_FILTER_ENTRY_TYPES },
-          b: { type: IML_FILTER_ENTRY_TYPES },
-          o: { enum: IML_BINARY_FILTER_OPERATORS }
+          a: operandSchema,
+          o: operatorSchema,
+          b: {
+            title: "Operand B",
+            description: "The second operand of the filter.",
+            type: IML_FILTER_ENTRY_TYPES
+          }
         },
         required: ["a", "b", "o"]
       }
     ]
   };
+  if (!operatorOptions) {
+    filterDefinition.oneOf?.push({
+      type: "object",
+      properties: {
+        a: operandSchema,
+        o: {
+          ...operatorSchema,
+          enum: IML_UNARY_FILTER_OPERATORS
+        }
+      },
+      required: ["a", "o"]
+    });
+  }
   const logic = field.logic ?? "default";
-  result.items = ["and", "or"].includes(logic) ? filterItems : {
+  result.items = ["and", "or"].includes(logic) ? filterDefinition : {
     type: "array",
-    items: filterItems
+    items: filterDefinition
   };
   Object.defineProperty(result, "x-filter", {
     configurable: true,
@@ -433,9 +776,7 @@ function handleSelectOrPathType(field, result, context) {
       }
     });
   }
-  const nested = isObject(field.options) ? isObject(field.options.nested) ? field.options.nested.store : field.options.nested : void 0;
-  const nestedContainsStrings = Array.isArray(nested) && nested.some((item) => typeof item === "string");
-  const domain = isObject(field.options) ? isObject(field.options.nested) && field.options.nested.domain ? field.options.nested.domain : void 0 : void 0;
+  const { nested, domain } = extractNestedAndDomain(field);
   if (typeof optionsOrGroups === "string") {
     Object.defineProperty(result, "x-fetch", {
       configurable: true,
@@ -504,46 +845,7 @@ function handleSelectOrPathType(field, result, context) {
       result.enum = (options || []).map((option) => option.value);
     }
   }
-  if (nested && domain && domain !== context.domain) {
-    const normalizedNested = typeof nested === "string" ? [nested] : nested;
-    let root = context.roots[domain];
-    if (!root) {
-      const buffer = [];
-      root = context.roots[domain] = {
-        buffer,
-        addFields: (nested2, tail) => {
-          buffer.push(...nested2.map((field2) => ({ field: field2, tail })));
-        }
-      };
-    }
-    root.addFields(normalizedNested, [...context.tail, field.name]);
-  } else if (nested) {
-    Object.defineProperty(result, "x-nested", {
-      configurable: true,
-      enumerable: true,
-      writable: true,
-      value: typeof nested === "string" ? { $ref: appendQueryString(nested, context.domain, [...context.tail, field.name]) } : nestedContainsStrings ? {
-        type: "object",
-        allOf: nested.map(
-          (item) => typeof item === "string" ? { $ref: appendQueryString(item, context.domain, [...context.tail, field.name]) } : toJSONSchemaInternal(
-            { type: "collection", spec: [item] },
-            {
-              ...context,
-              domain: domain || context.domain,
-              tail: [...context.tail, field.name]
-            }
-          )
-        )
-      } : toJSONSchemaInternal(
-        { type: "collection", spec: nested },
-        {
-          ...context,
-          domain: domain || context.domain,
-          tail: [...context.tail, field.name]
-        }
-      )
-    });
-  }
+  result = handleNestedWithDomain(field, nested, domain, result, context);
   if (field.rpc) result = processRpcDirective(field, result, context);
   return result;
 }
@@ -566,6 +868,10 @@ function handlePrimitiveType(field, result, context) {
     }
   }
   if (field.rpc) result = processRpcDirective(field, result, context);
+  if (field.nested) {
+    const { nested, domain } = extractNestedAndDomain(field);
+    result = handleNestedWithDomain(field, nested, domain, result, context);
+  }
   return result;
 }
 function processRpcDirective(field, result, context) {
@@ -582,6 +888,60 @@ function processRpcDirective(field, result, context) {
   });
   return result;
 }
+function extractNestedAndDomain(field) {
+  const nested = isObject(field.options) ? isObject(field.options.nested) ? field.options.nested.store : field.options.nested : isObject(field.nested) ? field.nested.store : field.nested;
+  const domain = isObject(field.options) ? isObject(field.options.nested) && field.options.nested.domain ? field.options.nested.domain : void 0 : isObject(field.nested) && field.nested.domain ? field.nested.domain : void 0;
+  return { nested, domain };
+}
+function handleNestedWithDomain(field, nested, domain, result, context) {
+  if (!nested) return result;
+  if (domain && domain !== context.domain) {
+    const normalizedNested = typeof nested === "string" ? [nested] : nested;
+    let root = context.roots[domain];
+    if (!root) {
+      const buffer = [];
+      root = context.roots[domain] = {
+        buffer,
+        addFields: (nested2, tail) => {
+          buffer.push(...nested2.map((field2) => ({ field: field2, tail })));
+        }
+      };
+    }
+    root.addFields(normalizedNested, [...context.tail, field.name]);
+    return result;
+  }
+  return processNestedDirective(field, nested, domain, result, context);
+}
+function processNestedDirective(field, nested, domain, result, context) {
+  if (!nested) return result;
+  const nestedContainsStrings = Array.isArray(nested) && nested.some((item) => typeof item === "string");
+  Object.defineProperty(result, "x-nested", {
+    configurable: true,
+    enumerable: true,
+    writable: true,
+    value: typeof nested === "string" ? { $ref: appendQueryString(nested, context.domain, [...context.tail, field.name]) } : nestedContainsStrings ? {
+      type: "object",
+      allOf: nested.map(
+        (item) => typeof item === "string" ? { $ref: appendQueryString(item, context.domain, [...context.tail, field.name]) } : toJSONSchemaInternal(
+          { type: "collection", spec: [item] },
+          {
+            ...context,
+            domain: domain || context.domain,
+            tail: [...context.tail, field.name]
+          }
+        )
+      )
+    } : toJSONSchemaInternal(
+      { type: "collection", spec: nested },
+      {
+        ...context,
+        domain: domain || context.domain,
+        tail: [...context.tail, field.name]
+      }
+    )
+  });
+  return result;
+}
 
 // src/validator.ts
 var FORMAN_TYPE_MAP2 = {
@@ -616,6 +976,8 @@ var FORMAN_TYPE_MAP2 = {
   pkey: "string",
   port: "number",
   select: void 0,
+  udttype: "string",
+  udtspec: "array",
   time: "string",
   timestamp: "string",
   timezone: "string",
@@ -756,6 +1118,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);
@@ -903,24 +1271,40 @@ async function handleArrayType2(value, field, context) {
   };
 }
 async function handleFilterType2(value, field, context) {
+  const operandOptions = isObject(field.options) ? field.options.store : field.options;
+  const operandSpec = {
+    name: "a",
+    type: "any",
+    required: true
+  };
+  if (Array.isArray(operandOptions)) {
+    operandSpec.type = "select";
+    operandSpec.options = operandOptions;
+  }
+  const operatorOptions = isObject(field.options) ? field.options.operators : void 0;
+  const operatorSpec = {
+    name: "o",
+    type: "any",
+    required: true
+  };
+  if (Array.isArray(operatorOptions)) {
+    operatorSpec.type = "select";
+    operatorSpec.grouped = true;
+    operatorSpec.options = operatorOptions;
+  } else {
+    operatorSpec.type = "text";
+    operatorSpec.validate = {
+      enum: IML_FILTER_OPERATORS
+    };
+  }
   const filterEntry = {
     type: "collection",
     spec: [
-      {
-        name: "a",
-        type: "any",
-        required: true
-      },
+      operandSpec,
+      operatorSpec,
       {
         name: "b",
         type: "any"
-      },
-      {
-        name: "o",
-        type: "text",
-        validate: {
-          enum: IML_FILTER_OPERATORS
-        }
       }
     ]
   };
@@ -1089,7 +1473,18 @@ 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,
@@ -1199,7 +1594,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,
@@ -1307,6 +1707,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) {
@@ -1429,7 +1832,17 @@ 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);

package/package.json

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