@makehq/forman-schema 1.15.0 → 1.17.0

package/README.md

@@ -291,11 +291,53 @@ const result = await validateFormanWithDomains(
 - object → collection
 - array → array
 
+## Field type resolution
+
+Field types resolve through three steps, so schemas authored with loose casing or common synonyms
+still convert:
+
+1. **Exact match** against `FORMAN_TYPE_MAP`.
+2. **Case-insensitive match** — `fileName`, `Boolean`, `URL`, `Select` resolve to their canonical
+   lowercase types. The index is derived from the map itself, so new entries get this for free.
+3. **Aliases** — `string→text`, `bool→boolean`, `datetime→date`, `float→number`,
+   `upload→filestorage`. Only unambiguous, information-preserving synonyms are aliased.
+
+A `type:kind` suffix (`account:google`, `device:apn`) resolves on its base type and keeps the kind,
+which drives the `api://` store expansion.
+
+### Unconvertible fields
+
+A field whose type is **missing or unresolvable** is degraded to a permissive typeless schema (the
+same shape `any` produces) instead of aborting the conversion, and its dot-notation path is reported
+on `toJSONSchemaAdvanced`'s `skippedPaths.unconvertible`:
+
+```js
+const { schema, skippedPaths } = toJSONSchemaAdvanced({
+    name: 'wrapper',
+    type: 'collection',
+    spec: [
+        { name: 'good', type: 'text' },
+        { name: 'odd', type: 'somethingNew' },
+    ],
+});
+// schema.properties → { good: { type: 'string' }, odd: {} }
+// skippedPaths      → { unconvertible: ['wrapper.odd (unknown type: somethingNew)'] }
+```
+
+This is deliberate: the throw was fatal at any depth, so a single unrecognized leaf field destroyed
+the whole schema and left consumers with nothing. Types requiring a guess about intent (`tags`,
+`category`, `object`) are degraded rather than aliased — a degraded field is honest, a wrongly
+aliased one is a lie the consumer will act on.
+
+Pass `{ strictFieldTypes: true }` to restore fail-fast throwing.
+
 ## Error Handling
 
 ### SchemaConversionError
 
-`SchemaConversionError` is thrown when schema conversion fails. It includes a message and optionally the field that caused the error.
+`SchemaConversionError` is thrown when schema conversion fails, and for unresolvable field types
+only when `strictFieldTypes: true` is set. It carries a message and the `field` that caused the
+error.
 
 ## Testing
 

package/dist/index.cjs

@@ -20,6 +20,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  SchemaConversionError: () => SchemaConversionError,
+  resolveFormanFieldType: () => resolveFormanFieldType,
   toFormanSchema: () => toFormanSchema,
   toJSONSchema: () => toJSONSchema,
   toJSONSchemaAdvanced: () => toJSONSchemaAdvanced,
@@ -216,7 +218,7 @@ function buildRestoreStructure(items) {
             }
             current = current[key].items;
           } else {
-            if (!current[key].nested) {
+            if (!current[key].nested || typeof current[key].nested !== "object" || Array.isArray(current[key].nested)) {
               current[key].nested = {};
             }
             current = current[key].nested;
@@ -543,11 +545,13 @@ var SchemaConversionError = class extends Error {
   constructor(message, field) {
     super(message);
     this.name = "SchemaConversionError";
+    this.field = field;
   }
 };
 var FORMAN_TYPE_MAP = {
   account: "number",
   hook: "number",
+  device: "number",
   keychain: "number",
   datastore: "number",
   aiagent: "string",
@@ -591,14 +595,29 @@ var FORMAN_TYPE_MAP = {
   uuid: "string",
   any: void 0
 };
-function validateFormanField(field) {
-  if (!field.type) {
-    throw new SchemaConversionError("Field type is required", field);
-  }
-  const normalizedType = field.type.includes(":") ? field.type.split(":")[0] : field.type;
-  if (!Object.keys(FORMAN_TYPE_MAP).includes(normalizedType)) {
-    throw new SchemaConversionError(`Unknown field type: ${field.type}`, field);
-  }
+var FORMAN_TYPE_LOOKUP = new Map(
+  Object.keys(FORMAN_TYPE_MAP).map((key) => [key.toLowerCase(), key])
+);
+var FORMAN_TYPE_ALIASES = {
+  // Forman's plain-string primitive is `text`; there is no `string` type.
+  string: "text",
+  bool: "boolean",
+  // Forman's `date` already carries time (see `time` on FormanSchemaField, default true).
+  datetime: "date",
+  // JSON Schema has no float; `number` is the only target.
+  float: "number",
+  // `upload` is the validator's existing name for the same array-shaped type.
+  upload: "filestorage"
+};
+function resolveFormanFieldType(rawType) {
+  if (!rawType) return void 0;
+  const base = rawType.includes(":") ? rawType.split(":")[0] : rawType;
+  const lower = base.toLowerCase();
+  return FORMAN_TYPE_LOOKUP.get(lower) ?? FORMAN_TYPE_ALIASES[lower];
+}
+function canonicalTypeWithKind(rawType, canonicalType) {
+  const separatorIndex = rawType.indexOf(":");
+  return separatorIndex === -1 ? canonicalType : `${canonicalType}${rawType.slice(separatorIndex)}`;
 }
 function appendQueryString(path, domain, tail) {
   if (path.startsWith("api://")) return path;
@@ -616,6 +635,7 @@ function createDefaultContext(options) {
     roots: {},
     definitions: {},
     excludeAdvancedFields: options?.excludeAdvancedFields ?? false,
+    strictFieldTypes: options?.strictFieldTypes ?? false,
     skippedPaths: {},
     addConditionalFields: () => {
       throw new SchemaConversionError("Cannot serialize nested fields without parent field.");
@@ -627,8 +647,19 @@ var compositeHandlers = {
   udttype: { expand: udttypeExpand, extractInner: udttypeExtractInner, wrapRef: udttypeWrapRef }
 };
 function toJSONSchemaInternal(field, context) {
-  validateFormanField(field);
-  const normalizedField = normalizeFormanFieldType(field);
+  const canonicalType = resolveFormanFieldType(field.type);
+  if (!canonicalType) {
+    if (context.strictFieldTypes) {
+      throw new SchemaConversionError(
+        field.type ? `Unknown field type: ${field.type}` : "Field type is required",
+        field
+      );
+    }
+    return degradeUnconvertibleField(field, context);
+  }
+  const normalizedField = normalizeFormanFieldType(
+    canonicalType === field.type ? field : { ...field, type: canonicalTypeWithKind(field.type, canonicalType) }
+  );
   const handler = compositeHandlers[normalizedField.type];
   if (handler) {
     const type = normalizedField.type;
@@ -1043,6 +1074,16 @@ function handleJsonType(field, result) {
   });
   return result;
 }
+function degradeUnconvertibleField(field, context) {
+  const path = field.name ? [...context.path, field.name].join(".") : context.path.join(".");
+  const reason = field.type ? `unknown type: ${field.type}` : "missing type";
+  (context.skippedPaths.unconvertible ||= []).push(`${path} (${reason})`);
+  return {
+    type: FORMAN_TYPE_MAP["any"],
+    title: noEmpty(field.label),
+    description: noEmpty(field.help)
+  };
+}
 function handlePrimitiveType(field, result, context) {
   if (field.default !== "" && field.default != null) {
     result.default = field.default;
@@ -1359,6 +1400,19 @@ async function validateFormanValue(value, field, context) {
       warnings: []
     };
   }
+  if (!field.type) {
+    return {
+      valid: false,
+      errors: [
+        {
+          domain: context.domain,
+          path: context.path.join("."),
+          message: "Field type is required."
+        }
+      ],
+      warnings: []
+    };
+  }
   const normalizedField = normalizeFormanFieldType(field);
   if (normalizedField.required && (value == null || value === "")) {
     return {
@@ -1917,7 +1971,8 @@ async function handleSelectType(value, field, context) {
         path: context.path,
         state: {
           mode: "chose",
-          label: placeholder.label
+          label: placeholder.label,
+          ...placeholder.nested ? { nested: placeholder.nested } : {}
         }
       });
     }
@@ -1955,7 +2010,8 @@ async function handleSelectType(value, field, context) {
           path: context.path,
           state: {
             mode: isReferenceType(field.type) ? void 0 : "chose",
-            label: item.label
+            label: item.label,
+            ...item.nested ? { nested: item.nested } : {}
           }
         });
       }
@@ -2302,6 +2358,9 @@ function toJSONSchemaAdvanced(field, options) {
   if (context.skippedPaths.advanced?.length) {
     skippedPaths.advanced = context.skippedPaths.advanced;
   }
+  if (context.skippedPaths.unconvertible?.length) {
+    skippedPaths.unconvertible = context.skippedPaths.unconvertible;
+  }
   return {
     schema,
     ...Object.keys(skippedPaths).length > 0 ? { skippedPaths } : {}
@@ -2321,6 +2380,8 @@ function validateForman(values, schema, options, restoreExtras) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  SchemaConversionError,
+  resolveFormanFieldType,
   toFormanSchema,
   toJSONSchema,
   toJSONSchemaAdvanced,

package/dist/index.d.cts

@@ -221,7 +221,12 @@ type FormanSchemaFieldState = {
     path?: Array<string>;
     data?: Record<string, unknown>;
     extra?: Record<string, unknown>;
-    nested?: Record<string, FormanSchemaFieldState>;
+    /**
+     * Child field states (record, built from field paths) or, on `chose` states of
+     * select-like fields, the chosen option's nested field specification — the UI
+     * persists that spec in `metadata.restore` to render the dependent fields.
+     */
+    nested?: Record<string, FormanSchemaFieldState> | FormanSchemaNested;
     items?: Record<string, FormanSchemaFieldState>[];
 };
 /**
@@ -235,6 +240,14 @@ type FormanJsonSchemaOptions = {
      * `toJSONSchemaAdvanced`'s `skippedPaths.advanced` so the caller can re-request them.
      */
     excludeAdvancedFields?: boolean;
+    /**
+     * Throw a `SchemaConversionError` when a field's type cannot be resolved, instead of degrading
+     * it to a permissive typeless schema. Defaults to `false` — by default, unresolvable fields are
+     * degraded and their dot-notation paths reported on `toJSONSchemaAdvanced`'s
+     * `skippedPaths.unconvertible`, so one unrecognized field can no longer abort the whole
+     * conversion. Set `true` only when a caller genuinely wants fail-fast behaviour.
+     */
+    strictFieldTypes?: boolean;
 };
 /**
  * Result of converting a Forman Schema to JSON Schema
@@ -246,6 +259,12 @@ type FormanJsonSchemaResult = {
     skippedPaths?: {
         /** Dot-notation paths of advanced fields that were skipped. Present only when at least one advanced field was skipped. */
         advanced?: string[];
+        /**
+         * Dot-notation paths of fields whose type could not be resolved and were therefore degraded
+         * to a permissive typeless schema. Each entry is suffixed with the reason —
+         * `(unknown type: X)` or `(missing type)`. Present only when at least one field was degraded.
+         */
+        unconvertible?: string[];
     };
 };
 /**
@@ -289,6 +308,26 @@ type FormanValidationOptions = {
  */
 declare function toFormanSchema(field: JSONSchema7): FormanSchemaField;
 
+/**
+ * Error thrown when schema conversion fails
+ */
+declare class SchemaConversionError extends Error {
+    /** Field that caused the error */
+    readonly field?: FormanSchemaField | JSONSchema7;
+    /**
+     * @param message The error message
+     * @param field The field that caused the error
+     */
+    constructor(message: string, field?: FormanSchemaField | JSONSchema7);
+}
+/**
+ * Resolves a raw Forman field type to a canonical `FORMAN_TYPE_MAP` key, handling `type:kind`
+ * prefixes, casing and known aliases.
+ * @param rawType The raw field type from the Forman schema
+ * @returns The canonical type key, or `undefined` when the type is missing or unresolvable
+ */
+declare function resolveFormanFieldType(rawType: string | undefined): string | undefined;
+
 /**
  * Converts a Forman Schema field to its JSON Schema equivalent and reports the paths of any
  * fields that were skipped during conversion.
@@ -306,6 +345,13 @@ declare function toFormanSchema(field: JSONSchema7): FormanSchemaField;
  * `definitions[type]`; advanced fields inside a composite template are recorded with the
  * path of the FIRST usage only. See the comment near `compositeHandlers` in `src/forman.ts`.
  *
+ * **Unresolvable field types** are tolerated by default. A field whose type is missing, or is not a
+ * known type (after case-insensitive and alias resolution), is degraded to a permissive typeless
+ * schema rather than aborting the whole conversion, and its dot-notation path is reported on
+ * `skippedPaths.unconvertible` with the reason. This matters because the throw was fatal at any
+ * depth: a single unrecognized leaf field destroyed the entire schema, leaving consumers with
+ * nothing. Pass `{ strictFieldTypes: true }` to restore fail-fast throwing.
+ *
  * If you don't need `skippedPaths`, use {@link toJSONSchema} which returns just the schema.
  *
  * @param field The Forman Schema field to convert
@@ -321,6 +367,9 @@ declare function toJSONSchemaAdvanced(field: FormanSchemaField, options?: Forman
  * fields were dropped (e.g. to render a "show advanced" toggle), use {@link toJSONSchemaAdvanced}
  * which returns `{ schema, skippedPaths? }`.
  *
+ * Fields with an unresolvable type are degraded to a permissive schema rather than throwing; use
+ * {@link toJSONSchemaAdvanced} to see which, or `{ strictFieldTypes: true }` to throw instead.
+ *
  * @param field The Forman Schema field to convert
  * @param options Conversion options
  * @returns The equivalent JSON Schema
@@ -353,4 +402,4 @@ declare function validateFormanWithDomains(domains: Record<string, {
  */
 declare function validateForman(values: Record<string, unknown>, schema: FormanSchemaField[], options?: FormanValidationOptions, restoreExtras?: Record<string, Record<string, unknown>>): Promise<FormanValidationResult>;
 
-export { type FormanExternalValidationResult, type FormanJsonSchemaOptions, type FormanJsonSchemaResult, type FormanSchemaDirectoryOption, type FormanSchemaExtendedNested, type FormanSchemaExtendedOptions, type FormanSchemaField, type FormanSchemaFieldType, type FormanSchemaNested, type FormanSchemaOption, type FormanSchemaOptionGroup, type FormanSchemaPathExtendedOptions, type FormanSchemaRPCButton, type FormanSchemaValue, type FormanValidationOptions, type FormanValidationResult, toFormanSchema, toJSONSchema, toJSONSchemaAdvanced, validateForman, validateFormanWithDomains };
+export { type FormanExternalValidationResult, type FormanJsonSchemaOptions, type FormanJsonSchemaResult, type FormanSchemaDirectoryOption, type FormanSchemaExtendedNested, type FormanSchemaExtendedOptions, type FormanSchemaField, type FormanSchemaFieldType, type FormanSchemaNested, type FormanSchemaOption, type FormanSchemaOptionGroup, type FormanSchemaPathExtendedOptions, type FormanSchemaRPCButton, type FormanSchemaValue, type FormanValidationOptions, type FormanValidationResult, SchemaConversionError, resolveFormanFieldType, toFormanSchema, toJSONSchema, toJSONSchemaAdvanced, validateForman, validateFormanWithDomains };

package/dist/index.d.ts

@@ -221,7 +221,12 @@ type FormanSchemaFieldState = {
     path?: Array<string>;
     data?: Record<string, unknown>;
     extra?: Record<string, unknown>;
-    nested?: Record<string, FormanSchemaFieldState>;
+    /**
+     * Child field states (record, built from field paths) or, on `chose` states of
+     * select-like fields, the chosen option's nested field specification — the UI
+     * persists that spec in `metadata.restore` to render the dependent fields.
+     */
+    nested?: Record<string, FormanSchemaFieldState> | FormanSchemaNested;
     items?: Record<string, FormanSchemaFieldState>[];
 };
 /**
@@ -235,6 +240,14 @@ type FormanJsonSchemaOptions = {
      * `toJSONSchemaAdvanced`'s `skippedPaths.advanced` so the caller can re-request them.
      */
     excludeAdvancedFields?: boolean;
+    /**
+     * Throw a `SchemaConversionError` when a field's type cannot be resolved, instead of degrading
+     * it to a permissive typeless schema. Defaults to `false` — by default, unresolvable fields are
+     * degraded and their dot-notation paths reported on `toJSONSchemaAdvanced`'s
+     * `skippedPaths.unconvertible`, so one unrecognized field can no longer abort the whole
+     * conversion. Set `true` only when a caller genuinely wants fail-fast behaviour.
+     */
+    strictFieldTypes?: boolean;
 };
 /**
  * Result of converting a Forman Schema to JSON Schema
@@ -246,6 +259,12 @@ type FormanJsonSchemaResult = {
     skippedPaths?: {
         /** Dot-notation paths of advanced fields that were skipped. Present only when at least one advanced field was skipped. */
         advanced?: string[];
+        /**
+         * Dot-notation paths of fields whose type could not be resolved and were therefore degraded
+         * to a permissive typeless schema. Each entry is suffixed with the reason —
+         * `(unknown type: X)` or `(missing type)`. Present only when at least one field was degraded.
+         */
+        unconvertible?: string[];
     };
 };
 /**
@@ -289,6 +308,26 @@ type FormanValidationOptions = {
  */
 declare function toFormanSchema(field: JSONSchema7): FormanSchemaField;
 
+/**
+ * Error thrown when schema conversion fails
+ */
+declare class SchemaConversionError extends Error {
+    /** Field that caused the error */
+    readonly field?: FormanSchemaField | JSONSchema7;
+    /**
+     * @param message The error message
+     * @param field The field that caused the error
+     */
+    constructor(message: string, field?: FormanSchemaField | JSONSchema7);
+}
+/**
+ * Resolves a raw Forman field type to a canonical `FORMAN_TYPE_MAP` key, handling `type:kind`
+ * prefixes, casing and known aliases.
+ * @param rawType The raw field type from the Forman schema
+ * @returns The canonical type key, or `undefined` when the type is missing or unresolvable
+ */
+declare function resolveFormanFieldType(rawType: string | undefined): string | undefined;
+
 /**
  * Converts a Forman Schema field to its JSON Schema equivalent and reports the paths of any
  * fields that were skipped during conversion.
@@ -306,6 +345,13 @@ declare function toFormanSchema(field: JSONSchema7): FormanSchemaField;
  * `definitions[type]`; advanced fields inside a composite template are recorded with the
  * path of the FIRST usage only. See the comment near `compositeHandlers` in `src/forman.ts`.
  *
+ * **Unresolvable field types** are tolerated by default. A field whose type is missing, or is not a
+ * known type (after case-insensitive and alias resolution), is degraded to a permissive typeless
+ * schema rather than aborting the whole conversion, and its dot-notation path is reported on
+ * `skippedPaths.unconvertible` with the reason. This matters because the throw was fatal at any
+ * depth: a single unrecognized leaf field destroyed the entire schema, leaving consumers with
+ * nothing. Pass `{ strictFieldTypes: true }` to restore fail-fast throwing.
+ *
  * If you don't need `skippedPaths`, use {@link toJSONSchema} which returns just the schema.
  *
  * @param field The Forman Schema field to convert
@@ -321,6 +367,9 @@ declare function toJSONSchemaAdvanced(field: FormanSchemaField, options?: Forman
  * fields were dropped (e.g. to render a "show advanced" toggle), use {@link toJSONSchemaAdvanced}
  * which returns `{ schema, skippedPaths? }`.
  *
+ * Fields with an unresolvable type are degraded to a permissive schema rather than throwing; use
+ * {@link toJSONSchemaAdvanced} to see which, or `{ strictFieldTypes: true }` to throw instead.
+ *
  * @param field The Forman Schema field to convert
  * @param options Conversion options
  * @returns The equivalent JSON Schema
@@ -353,4 +402,4 @@ declare function validateFormanWithDomains(domains: Record<string, {
  */
 declare function validateForman(values: Record<string, unknown>, schema: FormanSchemaField[], options?: FormanValidationOptions, restoreExtras?: Record<string, Record<string, unknown>>): Promise<FormanValidationResult>;
 
-export { type FormanExternalValidationResult, type FormanJsonSchemaOptions, type FormanJsonSchemaResult, type FormanSchemaDirectoryOption, type FormanSchemaExtendedNested, type FormanSchemaExtendedOptions, type FormanSchemaField, type FormanSchemaFieldType, type FormanSchemaNested, type FormanSchemaOption, type FormanSchemaOptionGroup, type FormanSchemaPathExtendedOptions, type FormanSchemaRPCButton, type FormanSchemaValue, type FormanValidationOptions, type FormanValidationResult, toFormanSchema, toJSONSchema, toJSONSchemaAdvanced, validateForman, validateFormanWithDomains };
+export { type FormanExternalValidationResult, type FormanJsonSchemaOptions, type FormanJsonSchemaResult, type FormanSchemaDirectoryOption, type FormanSchemaExtendedNested, type FormanSchemaExtendedOptions, type FormanSchemaField, type FormanSchemaFieldType, type FormanSchemaNested, type FormanSchemaOption, type FormanSchemaOptionGroup, type FormanSchemaPathExtendedOptions, type FormanSchemaRPCButton, type FormanSchemaValue, type FormanValidationOptions, type FormanValidationResult, SchemaConversionError, resolveFormanFieldType, toFormanSchema, toJSONSchema, toJSONSchemaAdvanced, validateForman, validateFormanWithDomains };

package/dist/index.js

@@ -186,7 +186,7 @@ function buildRestoreStructure(items) {
             }
             current = current[key].items;
           } else {
-            if (!current[key].nested) {
+            if (!current[key].nested || typeof current[key].nested !== "object" || Array.isArray(current[key].nested)) {
               current[key].nested = {};
             }
             current = current[key].nested;
@@ -513,11 +513,13 @@ var SchemaConversionError = class extends Error {
   constructor(message, field) {
     super(message);
     this.name = "SchemaConversionError";
+    this.field = field;
   }
 };
 var FORMAN_TYPE_MAP = {
   account: "number",
   hook: "number",
+  device: "number",
   keychain: "number",
   datastore: "number",
   aiagent: "string",
@@ -561,14 +563,29 @@ var FORMAN_TYPE_MAP = {
   uuid: "string",
   any: void 0
 };
-function validateFormanField(field) {
-  if (!field.type) {
-    throw new SchemaConversionError("Field type is required", field);
-  }
-  const normalizedType = field.type.includes(":") ? field.type.split(":")[0] : field.type;
-  if (!Object.keys(FORMAN_TYPE_MAP).includes(normalizedType)) {
-    throw new SchemaConversionError(`Unknown field type: ${field.type}`, field);
-  }
+var FORMAN_TYPE_LOOKUP = new Map(
+  Object.keys(FORMAN_TYPE_MAP).map((key) => [key.toLowerCase(), key])
+);
+var FORMAN_TYPE_ALIASES = {
+  // Forman's plain-string primitive is `text`; there is no `string` type.
+  string: "text",
+  bool: "boolean",
+  // Forman's `date` already carries time (see `time` on FormanSchemaField, default true).
+  datetime: "date",
+  // JSON Schema has no float; `number` is the only target.
+  float: "number",
+  // `upload` is the validator's existing name for the same array-shaped type.
+  upload: "filestorage"
+};
+function resolveFormanFieldType(rawType) {
+  if (!rawType) return void 0;
+  const base = rawType.includes(":") ? rawType.split(":")[0] : rawType;
+  const lower = base.toLowerCase();
+  return FORMAN_TYPE_LOOKUP.get(lower) ?? FORMAN_TYPE_ALIASES[lower];
+}
+function canonicalTypeWithKind(rawType, canonicalType) {
+  const separatorIndex = rawType.indexOf(":");
+  return separatorIndex === -1 ? canonicalType : `${canonicalType}${rawType.slice(separatorIndex)}`;
 }
 function appendQueryString(path, domain, tail) {
   if (path.startsWith("api://")) return path;
@@ -586,6 +603,7 @@ function createDefaultContext(options) {
     roots: {},
     definitions: {},
     excludeAdvancedFields: options?.excludeAdvancedFields ?? false,
+    strictFieldTypes: options?.strictFieldTypes ?? false,
     skippedPaths: {},
     addConditionalFields: () => {
       throw new SchemaConversionError("Cannot serialize nested fields without parent field.");
@@ -597,8 +615,19 @@ var compositeHandlers = {
   udttype: { expand: udttypeExpand, extractInner: udttypeExtractInner, wrapRef: udttypeWrapRef }
 };
 function toJSONSchemaInternal(field, context) {
-  validateFormanField(field);
-  const normalizedField = normalizeFormanFieldType(field);
+  const canonicalType = resolveFormanFieldType(field.type);
+  if (!canonicalType) {
+    if (context.strictFieldTypes) {
+      throw new SchemaConversionError(
+        field.type ? `Unknown field type: ${field.type}` : "Field type is required",
+        field
+      );
+    }
+    return degradeUnconvertibleField(field, context);
+  }
+  const normalizedField = normalizeFormanFieldType(
+    canonicalType === field.type ? field : { ...field, type: canonicalTypeWithKind(field.type, canonicalType) }
+  );
   const handler = compositeHandlers[normalizedField.type];
   if (handler) {
     const type = normalizedField.type;
@@ -1013,6 +1042,16 @@ function handleJsonType(field, result) {
   });
   return result;
 }
+function degradeUnconvertibleField(field, context) {
+  const path = field.name ? [...context.path, field.name].join(".") : context.path.join(".");
+  const reason = field.type ? `unknown type: ${field.type}` : "missing type";
+  (context.skippedPaths.unconvertible ||= []).push(`${path} (${reason})`);
+  return {
+    type: FORMAN_TYPE_MAP["any"],
+    title: noEmpty(field.label),
+    description: noEmpty(field.help)
+  };
+}
 function handlePrimitiveType(field, result, context) {
   if (field.default !== "" && field.default != null) {
     result.default = field.default;
@@ -1329,6 +1368,19 @@ async function validateFormanValue(value, field, context) {
       warnings: []
     };
   }
+  if (!field.type) {
+    return {
+      valid: false,
+      errors: [
+        {
+          domain: context.domain,
+          path: context.path.join("."),
+          message: "Field type is required."
+        }
+      ],
+      warnings: []
+    };
+  }
   const normalizedField = normalizeFormanFieldType(field);
   if (normalizedField.required && (value == null || value === "")) {
     return {
@@ -1887,7 +1939,8 @@ async function handleSelectType(value, field, context) {
         path: context.path,
         state: {
           mode: "chose",
-          label: placeholder.label
+          label: placeholder.label,
+          ...placeholder.nested ? { nested: placeholder.nested } : {}
         }
       });
     }
@@ -1925,7 +1978,8 @@ async function handleSelectType(value, field, context) {
           path: context.path,
           state: {
             mode: isReferenceType(field.type) ? void 0 : "chose",
-            label: item.label
+            label: item.label,
+            ...item.nested ? { nested: item.nested } : {}
           }
         });
       }
@@ -2272,6 +2326,9 @@ function toJSONSchemaAdvanced(field, options) {
   if (context.skippedPaths.advanced?.length) {
     skippedPaths.advanced = context.skippedPaths.advanced;
   }
+  if (context.skippedPaths.unconvertible?.length) {
+    skippedPaths.unconvertible = context.skippedPaths.unconvertible;
+  }
   return {
     schema,
     ...Object.keys(skippedPaths).length > 0 ? { skippedPaths } : {}
@@ -2290,6 +2347,8 @@ function validateForman(values, schema, options, restoreExtras) {
   );
 }
 export {
+  SchemaConversionError,
+  resolveFormanFieldType,
   toFormanSchema,
   toJSONSchema,
   toJSONSchemaAdvanced,

package/package.json

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