@makehq/forman-schema 1.14.0 → 1.16.0

package/README.md

@@ -80,6 +80,56 @@ const jsonSchemaField = {
 const formanSchema = toFormanSchema(jsonSchemaField);
 ```
 
+### JSON fields (`type: 'json'`)
+
+A `json` field can carry an explicit `schema` (a JSON Schema). This lets you author complex parts of a form directly in JSON Schema and mix them with primitive Forman fields:
+
+```typescript
+const formanField = {
+    type: 'collection',
+    spec: [
+        { name: 'title', type: 'text' },
+        {
+            name: 'input',
+            type: 'json',
+            schema: {
+                type: 'object',
+                properties: {
+                    name: { type: 'string' },
+                    age: { type: 'number' },
+                },
+            },
+        },
+    ],
+};
+```
+
+On conversion, the `schema` is **echoed verbatim** into the JSON Schema output (the field's `label`/`help` fill in `title`/`description` only when the schema omits them). An enumerable `x-json` marker is added so `toFormanSchema` can recover the `json` type; it survives JSON serialization. A `json` field **without** a `schema` renders as a plain object schema (`{ type: 'object' }`), since a JSON value is most naturally an object.
+
+#### External validators
+
+The library cannot validate a JSON value against an arbitrary JSON Schema on its own — it has **no JSON Schema validator built in**. Validation of `json` fields is therefore opt-in: **a `json` value is not validated unless you provide a `validateJson` callback.** Without it, the value passes through untouched.
+
+This is the first of a general **external validator** concept: a callback that performs validation the library can't, and returns a `FormanExternalValidationResult` verdict (`{ valid, errors?, warnings? }`) that is spliced into the overall result. The callback may be async (awaited), and its `errors`/`warnings` are stamped with the field's domain and path automatically. A `valid: false` verdict always fails validation, even when it carries no messages.
+
+```typescript
+import { validateForman, type FormanExternalValidationResult } from '@makehq/forman-schema';
+import Ajv from 'ajv'; // any JSON Schema validator works
+
+const ajv = new Ajv({ allErrors: true });
+
+const result = await validateForman({ input: { name: 'Alice', age: 30 } }, schema, {
+    async validateJson(schema, value): Promise<FormanExternalValidationResult> {
+        const validate = ajv.compile(schema);
+        if (validate(value)) return { valid: true };
+        return {
+            valid: false,
+            errors: (validate.errors ?? []).map(e => `${e.instancePath} ${e.message}`),
+        };
+    },
+});
+```
+
 ### Validation
 
 Validate Forman values against a Forman Schema. Two entry points are available:
@@ -217,7 +267,7 @@ const result = await validateFormanWithDomains(
 - hidden → string
 - hook → number
 - integer → number
-- json → string
+- json → object (or its `schema` echoed verbatim when provided — see [JSON fields](#json-fields-type-json))
 - keychain → number
 - number → number
 - path → string

package/dist/index.cjs

@@ -216,7 +216,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;
@@ -561,7 +561,7 @@ var FORMAN_TYPE_MAP = {
   boolean: "boolean",
   checkbox: "boolean",
   date: "string",
-  json: "string",
+  json: "object",
   buffer: "string",
   cert: "string",
   color: "string",
@@ -671,6 +671,8 @@ function toJSONSchemaInternal(field, context) {
     case "collection":
     case "dynamicCollection":
       return handleCollectionType(normalizedField, result, context);
+    case "json":
+      return handleJsonType(normalizedField, result);
     case "array":
     case "filestorage":
       return handleArrayType(normalizedField, result, context);
@@ -1027,6 +1029,20 @@ function handleSelectOrPathType(field, result, context) {
   if (field.rpc) result = processRpcDirective(field, result, context);
   return result;
 }
+function handleJsonType(field, result) {
+  if (!isObject(field.schema)) {
+    return result;
+  }
+  delete result.type;
+  Object.assign(result, field.schema);
+  Object.defineProperty(result, "x-json", {
+    configurable: true,
+    enumerable: true,
+    writable: true,
+    value: true
+  });
+  return result;
+}
 function handlePrimitiveType(field, result, context) {
   if (field.default !== "" && field.default != null) {
     result.default = field.default;
@@ -1146,7 +1162,8 @@ var SCHEMA_STRIP_KEYS = [
   "tags",
   "extension",
   "codepage",
-  "logic"
+  "logic",
+  "schema"
 ];
 function clampFieldForSchema(field) {
   const clamped = { ...field };
@@ -1191,7 +1208,7 @@ var FORMAN_TYPE_MAP2 = {
   boolean: "boolean",
   checkbox: "boolean",
   date: "string",
-  json: "string",
+  json: void 0,
   buffer: "string",
   cert: "string",
   color: "string",
@@ -1286,7 +1303,8 @@ async function validateFormanWithDomainsInternal(domains, options) {
             ...data,
             ...localData
           });
-        }
+        },
+        validateJson: options?.validateJson
       }
     );
     errors.push(...result.errors);
@@ -1418,6 +1436,8 @@ async function validateFormanValue(value, field, context) {
     return validateFormanValue(value, udtspecExpand({ ...normalizedField }), context);
   }
   switch (normalizedField.type) {
+    case "json":
+      return handleJsonType2(value, normalizedField, context);
     case "collection":
       return handleCollectionType2(value, normalizedField, context);
     case "array":
@@ -1897,7 +1917,8 @@ async function handleSelectType(value, field, context) {
         path: context.path,
         state: {
           mode: "chose",
-          label: placeholder.label
+          label: placeholder.label,
+          ...placeholder.nested ? { nested: placeholder.nested } : {}
         }
       });
     }
@@ -1935,7 +1956,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 } : {}
           }
         });
       }
@@ -2018,6 +2040,35 @@ async function handleNestedFields(nested, value, field, context) {
     warnings
   };
 }
+async function handleJsonType2(value, field, context) {
+  const errors = [];
+  const warnings = [];
+  if (!isObject(field.schema) || !context.validateJson) {
+    return { valid: true, errors, warnings };
+  }
+  const path = context.path.join(".");
+  let fragment;
+  try {
+    fragment = await context.validateJson(field.schema, value);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : "JSON schema validation failed unexpectedly.";
+    return { valid: false, errors: [{ domain: context.domain, path, message }], warnings };
+  }
+  for (const message of fragment.errors ?? []) {
+    errors.push({ domain: context.domain, path, message });
+  }
+  for (const message of fragment.warnings ?? []) {
+    warnings.push({ domain: context.domain, path, message });
+  }
+  if (fragment.valid === false && errors.length === 0) {
+    errors.push({ domain: context.domain, path, message: "JSON value failed schema validation." });
+  }
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings
+  };
+}
 async function handlePrimitiveType2(value, field, context) {
   const errors = [];
   const warnings = [];
@@ -2098,6 +2149,11 @@ function toFormanSchema(field) {
   return result;
 }
 function toFormanSchemaInternal(field) {
+  if (Object.getOwnPropertyDescriptor(field, "x-json")?.value === true) {
+    const schema = { ...field };
+    delete schema["x-json"];
+    return { type: "json", schema };
+  }
   const compositeType = Object.getOwnPropertyDescriptor(field, "x-composite")?.value;
   if (compositeType === "udttype") return udttypeCollapse(field);
   if (compositeType === "udtspec") return udtspecCollapse(field);

package/dist/index.d.cts

@@ -41,6 +41,8 @@ type FormanSchemaField = {
     help?: string;
     /** Sub-fields specification for collection or array types */
     spec?: FormanSchemaField[] | FormanSchemaField;
+    /** JSON Schema for `json` typed fields */
+    schema?: JSONSchema7;
     /** Hide field behind advanced toggle */
     advanced?: boolean;
     /** Human readable label for the field */
@@ -219,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>[];
 };
 /**
@@ -246,6 +253,19 @@ type FormanJsonSchemaResult = {
         advanced?: string[];
     };
 };
+/**
+ * Verdict fragment returned by an external validation callback (e.g. `validateJson`) that the
+ * library cannot perform itself. Spliced into the overall validation result: `errors`/`warnings`
+ * are stamped with the field's domain and path.
+ */
+type FormanExternalValidationResult = {
+    /** Whether the value is valid. A `false` verdict always fails validation, even with no messages. */
+    valid: boolean;
+    /** Error messages (cause validation to fail) */
+    errors?: string[];
+    /** Warning messages (do not affect validity) */
+    warnings?: string[];
+};
 type FormanValidationOptions = {
     /** Unknown fields are not allowed when strict is true */
     strict?: boolean;
@@ -255,6 +275,10 @@ type FormanValidationOptions = {
     schemas?: boolean;
     /** Remote resource resolver */
     resolveRemote?(path: string, data: Record<string, unknown>): Promise<unknown>;
+    /** Validator for `json` typed fields. Receives the field's JSON Schema and the value, and
+     *  returns (or resolves to) a result fragment that is spliced into the overall validation
+     *  result. When omitted, `json` fields with a `schema` pass without schema validation. */
+    validateJson?(schema: JSONSchema7, value: unknown): FormanExternalValidationResult | Promise<FormanExternalValidationResult>;
     /** Maps domain names used in nested.domain to actual domain keys passed to validateFormanWithDomains */
     domainAliases?: Record<string, string>;
     /** Whether to allow dynamic values (IML expressions, unresolved RPC options).
@@ -334,4 +358,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 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, toFormanSchema, toJSONSchema, toJSONSchemaAdvanced, validateForman, validateFormanWithDomains };

package/dist/index.d.ts

@@ -41,6 +41,8 @@ type FormanSchemaField = {
     help?: string;
     /** Sub-fields specification for collection or array types */
     spec?: FormanSchemaField[] | FormanSchemaField;
+    /** JSON Schema for `json` typed fields */
+    schema?: JSONSchema7;
     /** Hide field behind advanced toggle */
     advanced?: boolean;
     /** Human readable label for the field */
@@ -219,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>[];
 };
 /**
@@ -246,6 +253,19 @@ type FormanJsonSchemaResult = {
         advanced?: string[];
     };
 };
+/**
+ * Verdict fragment returned by an external validation callback (e.g. `validateJson`) that the
+ * library cannot perform itself. Spliced into the overall validation result: `errors`/`warnings`
+ * are stamped with the field's domain and path.
+ */
+type FormanExternalValidationResult = {
+    /** Whether the value is valid. A `false` verdict always fails validation, even with no messages. */
+    valid: boolean;
+    /** Error messages (cause validation to fail) */
+    errors?: string[];
+    /** Warning messages (do not affect validity) */
+    warnings?: string[];
+};
 type FormanValidationOptions = {
     /** Unknown fields are not allowed when strict is true */
     strict?: boolean;
@@ -255,6 +275,10 @@ type FormanValidationOptions = {
     schemas?: boolean;
     /** Remote resource resolver */
     resolveRemote?(path: string, data: Record<string, unknown>): Promise<unknown>;
+    /** Validator for `json` typed fields. Receives the field's JSON Schema and the value, and
+     *  returns (or resolves to) a result fragment that is spliced into the overall validation
+     *  result. When omitted, `json` fields with a `schema` pass without schema validation. */
+    validateJson?(schema: JSONSchema7, value: unknown): FormanExternalValidationResult | Promise<FormanExternalValidationResult>;
     /** Maps domain names used in nested.domain to actual domain keys passed to validateFormanWithDomains */
     domainAliases?: Record<string, string>;
     /** Whether to allow dynamic values (IML expressions, unresolved RPC options).
@@ -334,4 +358,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 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, 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;
@@ -531,7 +531,7 @@ var FORMAN_TYPE_MAP = {
   boolean: "boolean",
   checkbox: "boolean",
   date: "string",
-  json: "string",
+  json: "object",
   buffer: "string",
   cert: "string",
   color: "string",
@@ -641,6 +641,8 @@ function toJSONSchemaInternal(field, context) {
     case "collection":
     case "dynamicCollection":
       return handleCollectionType(normalizedField, result, context);
+    case "json":
+      return handleJsonType(normalizedField, result);
     case "array":
     case "filestorage":
       return handleArrayType(normalizedField, result, context);
@@ -997,6 +999,20 @@ function handleSelectOrPathType(field, result, context) {
   if (field.rpc) result = processRpcDirective(field, result, context);
   return result;
 }
+function handleJsonType(field, result) {
+  if (!isObject(field.schema)) {
+    return result;
+  }
+  delete result.type;
+  Object.assign(result, field.schema);
+  Object.defineProperty(result, "x-json", {
+    configurable: true,
+    enumerable: true,
+    writable: true,
+    value: true
+  });
+  return result;
+}
 function handlePrimitiveType(field, result, context) {
   if (field.default !== "" && field.default != null) {
     result.default = field.default;
@@ -1116,7 +1132,8 @@ var SCHEMA_STRIP_KEYS = [
   "tags",
   "extension",
   "codepage",
-  "logic"
+  "logic",
+  "schema"
 ];
 function clampFieldForSchema(field) {
   const clamped = { ...field };
@@ -1161,7 +1178,7 @@ var FORMAN_TYPE_MAP2 = {
   boolean: "boolean",
   checkbox: "boolean",
   date: "string",
-  json: "string",
+  json: void 0,
   buffer: "string",
   cert: "string",
   color: "string",
@@ -1256,7 +1273,8 @@ async function validateFormanWithDomainsInternal(domains, options) {
             ...data,
             ...localData
           });
-        }
+        },
+        validateJson: options?.validateJson
       }
     );
     errors.push(...result.errors);
@@ -1388,6 +1406,8 @@ async function validateFormanValue(value, field, context) {
     return validateFormanValue(value, udtspecExpand({ ...normalizedField }), context);
   }
   switch (normalizedField.type) {
+    case "json":
+      return handleJsonType2(value, normalizedField, context);
     case "collection":
       return handleCollectionType2(value, normalizedField, context);
     case "array":
@@ -1867,7 +1887,8 @@ async function handleSelectType(value, field, context) {
         path: context.path,
         state: {
           mode: "chose",
-          label: placeholder.label
+          label: placeholder.label,
+          ...placeholder.nested ? { nested: placeholder.nested } : {}
         }
       });
     }
@@ -1905,7 +1926,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 } : {}
           }
         });
       }
@@ -1988,6 +2010,35 @@ async function handleNestedFields(nested, value, field, context) {
     warnings
   };
 }
+async function handleJsonType2(value, field, context) {
+  const errors = [];
+  const warnings = [];
+  if (!isObject(field.schema) || !context.validateJson) {
+    return { valid: true, errors, warnings };
+  }
+  const path = context.path.join(".");
+  let fragment;
+  try {
+    fragment = await context.validateJson(field.schema, value);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : "JSON schema validation failed unexpectedly.";
+    return { valid: false, errors: [{ domain: context.domain, path, message }], warnings };
+  }
+  for (const message of fragment.errors ?? []) {
+    errors.push({ domain: context.domain, path, message });
+  }
+  for (const message of fragment.warnings ?? []) {
+    warnings.push({ domain: context.domain, path, message });
+  }
+  if (fragment.valid === false && errors.length === 0) {
+    errors.push({ domain: context.domain, path, message: "JSON value failed schema validation." });
+  }
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings
+  };
+}
 async function handlePrimitiveType2(value, field, context) {
   const errors = [];
   const warnings = [];
@@ -2068,6 +2119,11 @@ function toFormanSchema(field) {
   return result;
 }
 function toFormanSchemaInternal(field) {
+  if (Object.getOwnPropertyDescriptor(field, "x-json")?.value === true) {
+    const schema = { ...field };
+    delete schema["x-json"];
+    return { type: "json", schema };
+  }
   const compositeType = Object.getOwnPropertyDescriptor(field, "x-composite")?.value;
   if (compositeType === "udttype") return udttypeCollapse(field);
   if (compositeType === "udtspec") return udtspecCollapse(field);

package/package.json

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