@makehq/forman-schema 1.13.2 → 1.15.0

package/README.md

@@ -2,6 +2,15 @@
 
 Conversion and validation utilities for Forman Schema.
 
+## v1.14.0 — advanced field tracking
+
+Non-breaking minor release. New surface for working with `advanced: true` Forman fields:
+
+- `toJSONSchema(field, options?)` still returns a bare `JSONSchema7` — fully backward-compatible.
+- Fields marked `advanced: true` are now stamped with `x-advanced: true` on the JSON Schema output, and round-trip through `toFormanSchema` (which restores `advanced: true`).
+- New option `excludeAdvancedFields?: boolean` (default `false`). When `true`, advanced sub-fields of a collection are omitted from the schema.
+- New function `toJSONSchemaAdvanced(field, options?)` returns `{ schema: JSONSchema7, skippedPaths?: { advanced?: string[] } }`. Use it to learn which advanced fields were dropped (e.g. to render a "show advanced" toggle). `toJSONSchema` delegates to it internally and returns just `.schema`.
+
 ## Installation
 
 ```bash
@@ -33,6 +42,23 @@ const formanField = {
 const jsonSchema = toJSONSchema(formanField);
 ```
 
+Advanced fields (`advanced: true`) are included by default and stamped with `x-advanced: true`. To omit them from the rendered schema, pass `{ excludeAdvancedFields: true }`:
+
+```typescript
+const jsonSchema = toJSONSchema(formanField, { excludeAdvancedFields: true });
+```
+
+If you also need to know **which** advanced fields were dropped (e.g. to render a "show advanced" toggle), use `toJSONSchemaAdvanced`:
+
+```typescript
+import { toJSONSchemaAdvanced } from '@makehq/forman-schema';
+
+const { schema, skippedPaths } = toJSONSchemaAdvanced(formanField, { excludeAdvancedFields: true });
+// skippedPaths?.advanced is an array of dot-notation paths like ['wrapper.field', 'wrapper.arr[].nested']
+```
+
+The filter applies to **sub-fields of a collection** — including nested-by-option fields, array-of-collection items, composite expansions (`udtspec`, `udttype`), and cross-domain buffered fields. It does **not** apply to: the top-level field passed in (always converted), or the item type of an array whose `spec` is a single primitive field. To hide an entire array or any other top-level structure, mark the _parent_ field as `advanced: true`.
+
 ### Converting from JSON Schema to Forman Schema
 
 ```typescript
@@ -54,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:
@@ -191,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

@@ -22,6 +22,7 @@ var index_exports = {};
 __export(index_exports, {
   toFormanSchema: () => toFormanSchema,
   toJSONSchema: () => toJSONSchema,
+  toJSONSchemaAdvanced: () => toJSONSchemaAdvanced,
   validateForman: () => validateForman,
   validateFormanWithDomains: () => validateFormanWithDomains
 });
@@ -560,7 +561,7 @@ var FORMAN_TYPE_MAP = {
   boolean: "boolean",
   checkbox: "boolean",
   date: "string",
-  json: "string",
+  json: "object",
   buffer: "string",
   cert: "string",
   color: "string",
@@ -607,13 +608,15 @@ function appendQueryString(path, domain, tail) {
   const separator = path.includes("?") ? "&" : "?";
   return `${path}${separator}${queryString}`;
 }
-function createDefaultContext() {
+function createDefaultContext(options) {
   return {
     domain: "default",
     tail: [],
     path: [],
     roots: {},
     definitions: {},
+    excludeAdvancedFields: options?.excludeAdvancedFields ?? false,
+    skippedPaths: {},
     addConditionalFields: () => {
       throw new SchemaConversionError("Cannot serialize nested fields without parent field.");
     }
@@ -668,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);
@@ -695,6 +700,7 @@ function handleCollectionType(field, result, context) {
     properties: {},
     required: []
   });
+  const collectionPath = field.name ? [...context.path, field.name] : context.path;
   function addField(subField, tail) {
     if (typeof subField === "string") {
       const value = { $ref: appendQueryString(subField, context.domain, tail || context.tail) };
@@ -707,28 +713,41 @@ function handleCollectionType(field, result, context) {
     }
     if (!subField.name) return;
     if (result.properties && Object.hasOwn(result.properties, subField.name)) return;
+    if (subField.advanced === true && context.excludeAdvancedFields) {
+      (context.skippedPaths.advanced ||= []).push([...collectionPath, subField.name].join("."));
+      return;
+    }
     if (subField.required) {
       result.required.push(subField.name);
     }
+    const subSchema = toJSONSchemaInternal(subField, {
+      ...context,
+      domain: field["x-domain-root"] || context.domain,
+      tail: tail || context.tail,
+      path: collectionPath,
+      addConditionalFields: (name, value, nested) => {
+        result.allOf ||= [];
+        result.allOf.push({
+          if: {
+            properties: {
+              [name]: { const: value }
+            }
+          },
+          then: typeof nested === "string" ? { $ref: nested } : nested
+        });
+      }
+    });
+    if (subField.advanced) {
+      Object.defineProperty(subSchema, "x-advanced", {
+        configurable: true,
+        enumerable: true,
+        writable: true,
+        value: true
+      });
+    }
     Object.defineProperty(result.properties, subField.name, {
       enumerable: true,
-      value: toJSONSchemaInternal(subField, {
-        ...context,
-        domain: field["x-domain-root"] || context.domain,
-        tail: tail || context.tail,
-        path: [...context.path, field.name],
-        addConditionalFields: (name, value, nested) => {
-          result.allOf ||= [];
-          result.allOf.push({
-            if: {
-              properties: {
-                [name]: { const: value }
-              }
-            },
-            then: typeof nested === "string" ? { $ref: nested } : nested
-          });
-        }
-      })
+      value: subSchema
     });
   }
   if (field["x-domain-root"]) {
@@ -1010,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;
@@ -1129,7 +1162,8 @@ var SCHEMA_STRIP_KEYS = [
   "tags",
   "extension",
   "codepage",
-  "logic"
+  "logic",
+  "schema"
 ];
 function clampFieldForSchema(field) {
   const clamped = { ...field };
@@ -1174,7 +1208,7 @@ var FORMAN_TYPE_MAP2 = {
   boolean: "boolean",
   checkbox: "boolean",
   date: "string",
-  json: "string",
+  json: void 0,
   buffer: "string",
   cert: "string",
   color: "string",
@@ -1269,7 +1303,8 @@ async function validateFormanWithDomainsInternal(domains, options) {
             ...data,
             ...localData
           });
-        }
+        },
+        validateJson: options?.validateJson
       }
     );
     errors.push(...result.errors);
@@ -1401,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":
@@ -2001,6 +2038,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 = [];
@@ -2074,6 +2140,18 @@ var JSON_PRIMITIVE_TYPE_MAP = {
   boolean: "boolean"
 };
 function toFormanSchema(field) {
+  const result = toFormanSchemaInternal(field);
+  if (Object.getOwnPropertyDescriptor(field, "x-advanced")?.value === true) {
+    result.advanced = true;
+  }
+  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);
@@ -2209,18 +2287,28 @@ function handleSearchDirective(formanField, directive) {
 }
 
 // src/index.ts
-function toJSONSchema(field) {
-  const context = createDefaultContext();
-  const result = toJSONSchemaInternal(field, context);
+function toJSONSchemaAdvanced(field, options) {
+  const context = createDefaultContext(options);
+  const schema = toJSONSchemaInternal(field, context);
   if (Object.keys(context.definitions ?? {}).length > 0) {
-    Object.defineProperty(result, "definitions", {
+    Object.defineProperty(schema, "definitions", {
       configurable: true,
       enumerable: true,
       writable: true,
       value: context.definitions
     });
   }
-  return result;
+  const skippedPaths = {};
+  if (context.skippedPaths.advanced?.length) {
+    skippedPaths.advanced = context.skippedPaths.advanced;
+  }
+  return {
+    schema,
+    ...Object.keys(skippedPaths).length > 0 ? { skippedPaths } : {}
+  };
+}
+function toJSONSchema(field, options) {
+  return toJSONSchemaAdvanced(field, options).schema;
 }
 function validateFormanWithDomains(domains, options) {
   return validateFormanWithDomainsInternal(domains, options);
@@ -2235,6 +2323,7 @@ function validateForman(values, schema, options, restoreExtras) {
 0 && (module.exports = {
   toFormanSchema,
   toJSONSchema,
+  toJSONSchemaAdvanced,
   validateForman,
   validateFormanWithDomains
 });

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 */
@@ -222,6 +224,43 @@ type FormanSchemaFieldState = {
     nested?: Record<string, FormanSchemaFieldState>;
     items?: Record<string, FormanSchemaFieldState>[];
 };
+/**
+ * Options for converting a Forman Schema to JSON Schema
+ */
+type FormanJsonSchemaOptions = {
+    /**
+     * Exclude fields marked `advanced: true` from the rendered schema. Defaults to `false`
+     * (advanced fields are included and stamped with `x-advanced: true`). When `true`,
+     * advanced fields are omitted; their dot-notation paths are reported on
+     * `toJSONSchemaAdvanced`'s `skippedPaths.advanced` so the caller can re-request them.
+     */
+    excludeAdvancedFields?: boolean;
+};
+/**
+ * Result of converting a Forman Schema to JSON Schema
+ */
+type FormanJsonSchemaResult = {
+    /** The converted JSON Schema */
+    schema: JSONSchema7;
+    /** Paths to fields that were skipped during conversion. Present only when at least one field was skipped. */
+    skippedPaths?: {
+        /** Dot-notation paths of advanced fields that were skipped. Present only when at least one advanced field was skipped. */
+        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;
@@ -231,6 +270,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).
@@ -246,12 +289,43 @@ type FormanValidationOptions = {
  */
 declare function toFormanSchema(field: JSONSchema7): FormanSchemaField;
 
+/**
+ * Converts a Forman Schema field to its JSON Schema equivalent and reports the paths of any
+ * fields that were skipped during conversion.
+ *
+ * **Advanced fields** (`advanced: true`) are included by default and stamped with
+ * `x-advanced: true` on the JSON Schema (the marker round-trips through `toFormanSchema`).
+ * Pass `{ excludeAdvancedFields: true }` to omit them — when excluded, the affected
+ * dot-notation paths are reported on `skippedPaths.advanced`. The filter applies to sub-fields
+ * of a collection (main form, nested-by-option, array-of-collection items, composite
+ * expansions, cross-domain buffered fields). It does NOT apply to the top-level field passed
+ * here, nor to the item type of an array whose `spec` is a single primitive field. Mark the
+ * parent as `advanced: true` to hide such structures.
+ *
+ * Known limitation: composite types (`udtspec`, `udttype`) are memoized in
+ * `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`.
+ *
+ * If you don't need `skippedPaths`, use {@link toJSONSchema} which returns just the schema.
+ *
+ * @param field The Forman Schema field to convert
+ * @param options Conversion options
+ * @returns The conversion result `{ schema, skippedPaths? }`. `skippedPaths` is omitted when nothing was skipped.
+ */
+declare function toJSONSchemaAdvanced(field: FormanSchemaField, options?: FormanJsonSchemaOptions): FormanJsonSchemaResult;
 /**
  * Converts a Forman Schema field to its JSON Schema equivalent.
+ *
+ * Advanced fields (`advanced: true`) are included by default and stamped with `x-advanced: true`.
+ * Pass `{ excludeAdvancedFields: true }` to omit them. If you need to know *which* advanced
+ * fields were dropped (e.g. to render a "show advanced" toggle), use {@link toJSONSchemaAdvanced}
+ * which returns `{ schema, skippedPaths? }`.
+ *
  * @param field The Forman Schema field to convert
- * @returns The equivalent JSON Schema field
+ * @param options Conversion options
+ * @returns The equivalent JSON Schema
  */
-declare function toJSONSchema(field: FormanSchemaField): JSONSchema7;
+declare function toJSONSchema(field: FormanSchemaField, options?: FormanJsonSchemaOptions): JSONSchema7;
 /**
  * Validates a Forman domains against schemas
  * @param domains The domains to validate
@@ -279,4 +353,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 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, 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 */
@@ -222,6 +224,43 @@ type FormanSchemaFieldState = {
     nested?: Record<string, FormanSchemaFieldState>;
     items?: Record<string, FormanSchemaFieldState>[];
 };
+/**
+ * Options for converting a Forman Schema to JSON Schema
+ */
+type FormanJsonSchemaOptions = {
+    /**
+     * Exclude fields marked `advanced: true` from the rendered schema. Defaults to `false`
+     * (advanced fields are included and stamped with `x-advanced: true`). When `true`,
+     * advanced fields are omitted; their dot-notation paths are reported on
+     * `toJSONSchemaAdvanced`'s `skippedPaths.advanced` so the caller can re-request them.
+     */
+    excludeAdvancedFields?: boolean;
+};
+/**
+ * Result of converting a Forman Schema to JSON Schema
+ */
+type FormanJsonSchemaResult = {
+    /** The converted JSON Schema */
+    schema: JSONSchema7;
+    /** Paths to fields that were skipped during conversion. Present only when at least one field was skipped. */
+    skippedPaths?: {
+        /** Dot-notation paths of advanced fields that were skipped. Present only when at least one advanced field was skipped. */
+        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;
@@ -231,6 +270,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).
@@ -246,12 +289,43 @@ type FormanValidationOptions = {
  */
 declare function toFormanSchema(field: JSONSchema7): FormanSchemaField;
 
+/**
+ * Converts a Forman Schema field to its JSON Schema equivalent and reports the paths of any
+ * fields that were skipped during conversion.
+ *
+ * **Advanced fields** (`advanced: true`) are included by default and stamped with
+ * `x-advanced: true` on the JSON Schema (the marker round-trips through `toFormanSchema`).
+ * Pass `{ excludeAdvancedFields: true }` to omit them — when excluded, the affected
+ * dot-notation paths are reported on `skippedPaths.advanced`. The filter applies to sub-fields
+ * of a collection (main form, nested-by-option, array-of-collection items, composite
+ * expansions, cross-domain buffered fields). It does NOT apply to the top-level field passed
+ * here, nor to the item type of an array whose `spec` is a single primitive field. Mark the
+ * parent as `advanced: true` to hide such structures.
+ *
+ * Known limitation: composite types (`udtspec`, `udttype`) are memoized in
+ * `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`.
+ *
+ * If you don't need `skippedPaths`, use {@link toJSONSchema} which returns just the schema.
+ *
+ * @param field The Forman Schema field to convert
+ * @param options Conversion options
+ * @returns The conversion result `{ schema, skippedPaths? }`. `skippedPaths` is omitted when nothing was skipped.
+ */
+declare function toJSONSchemaAdvanced(field: FormanSchemaField, options?: FormanJsonSchemaOptions): FormanJsonSchemaResult;
 /**
  * Converts a Forman Schema field to its JSON Schema equivalent.
+ *
+ * Advanced fields (`advanced: true`) are included by default and stamped with `x-advanced: true`.
+ * Pass `{ excludeAdvancedFields: true }` to omit them. If you need to know *which* advanced
+ * fields were dropped (e.g. to render a "show advanced" toggle), use {@link toJSONSchemaAdvanced}
+ * which returns `{ schema, skippedPaths? }`.
+ *
  * @param field The Forman Schema field to convert
- * @returns The equivalent JSON Schema field
+ * @param options Conversion options
+ * @returns The equivalent JSON Schema
  */
-declare function toJSONSchema(field: FormanSchemaField): JSONSchema7;
+declare function toJSONSchema(field: FormanSchemaField, options?: FormanJsonSchemaOptions): JSONSchema7;
 /**
  * Validates a Forman domains against schemas
  * @param domains The domains to validate
@@ -279,4 +353,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 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, 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

@@ -531,7 +531,7 @@ var FORMAN_TYPE_MAP = {
   boolean: "boolean",
   checkbox: "boolean",
   date: "string",
-  json: "string",
+  json: "object",
   buffer: "string",
   cert: "string",
   color: "string",
@@ -578,13 +578,15 @@ function appendQueryString(path, domain, tail) {
   const separator = path.includes("?") ? "&" : "?";
   return `${path}${separator}${queryString}`;
 }
-function createDefaultContext() {
+function createDefaultContext(options) {
   return {
     domain: "default",
     tail: [],
     path: [],
     roots: {},
     definitions: {},
+    excludeAdvancedFields: options?.excludeAdvancedFields ?? false,
+    skippedPaths: {},
     addConditionalFields: () => {
       throw new SchemaConversionError("Cannot serialize nested fields without parent field.");
     }
@@ -639,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);
@@ -666,6 +670,7 @@ function handleCollectionType(field, result, context) {
     properties: {},
     required: []
   });
+  const collectionPath = field.name ? [...context.path, field.name] : context.path;
   function addField(subField, tail) {
     if (typeof subField === "string") {
       const value = { $ref: appendQueryString(subField, context.domain, tail || context.tail) };
@@ -678,28 +683,41 @@ function handleCollectionType(field, result, context) {
     }
     if (!subField.name) return;
     if (result.properties && Object.hasOwn(result.properties, subField.name)) return;
+    if (subField.advanced === true && context.excludeAdvancedFields) {
+      (context.skippedPaths.advanced ||= []).push([...collectionPath, subField.name].join("."));
+      return;
+    }
     if (subField.required) {
       result.required.push(subField.name);
     }
+    const subSchema = toJSONSchemaInternal(subField, {
+      ...context,
+      domain: field["x-domain-root"] || context.domain,
+      tail: tail || context.tail,
+      path: collectionPath,
+      addConditionalFields: (name, value, nested) => {
+        result.allOf ||= [];
+        result.allOf.push({
+          if: {
+            properties: {
+              [name]: { const: value }
+            }
+          },
+          then: typeof nested === "string" ? { $ref: nested } : nested
+        });
+      }
+    });
+    if (subField.advanced) {
+      Object.defineProperty(subSchema, "x-advanced", {
+        configurable: true,
+        enumerable: true,
+        writable: true,
+        value: true
+      });
+    }
     Object.defineProperty(result.properties, subField.name, {
       enumerable: true,
-      value: toJSONSchemaInternal(subField, {
-        ...context,
-        domain: field["x-domain-root"] || context.domain,
-        tail: tail || context.tail,
-        path: [...context.path, field.name],
-        addConditionalFields: (name, value, nested) => {
-          result.allOf ||= [];
-          result.allOf.push({
-            if: {
-              properties: {
-                [name]: { const: value }
-              }
-            },
-            then: typeof nested === "string" ? { $ref: nested } : nested
-          });
-        }
-      })
+      value: subSchema
     });
   }
   if (field["x-domain-root"]) {
@@ -981,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;
@@ -1100,7 +1132,8 @@ var SCHEMA_STRIP_KEYS = [
   "tags",
   "extension",
   "codepage",
-  "logic"
+  "logic",
+  "schema"
 ];
 function clampFieldForSchema(field) {
   const clamped = { ...field };
@@ -1145,7 +1178,7 @@ var FORMAN_TYPE_MAP2 = {
   boolean: "boolean",
   checkbox: "boolean",
   date: "string",
-  json: "string",
+  json: void 0,
   buffer: "string",
   cert: "string",
   color: "string",
@@ -1240,7 +1273,8 @@ async function validateFormanWithDomainsInternal(domains, options) {
             ...data,
             ...localData
           });
-        }
+        },
+        validateJson: options?.validateJson
       }
     );
     errors.push(...result.errors);
@@ -1372,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":
@@ -1972,6 +2008,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 = [];
@@ -2045,6 +2110,18 @@ var JSON_PRIMITIVE_TYPE_MAP = {
   boolean: "boolean"
 };
 function toFormanSchema(field) {
+  const result = toFormanSchemaInternal(field);
+  if (Object.getOwnPropertyDescriptor(field, "x-advanced")?.value === true) {
+    result.advanced = true;
+  }
+  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);
@@ -2180,18 +2257,28 @@ function handleSearchDirective(formanField, directive) {
 }
 
 // src/index.ts
-function toJSONSchema(field) {
-  const context = createDefaultContext();
-  const result = toJSONSchemaInternal(field, context);
+function toJSONSchemaAdvanced(field, options) {
+  const context = createDefaultContext(options);
+  const schema = toJSONSchemaInternal(field, context);
   if (Object.keys(context.definitions ?? {}).length > 0) {
-    Object.defineProperty(result, "definitions", {
+    Object.defineProperty(schema, "definitions", {
       configurable: true,
       enumerable: true,
       writable: true,
       value: context.definitions
     });
   }
-  return result;
+  const skippedPaths = {};
+  if (context.skippedPaths.advanced?.length) {
+    skippedPaths.advanced = context.skippedPaths.advanced;
+  }
+  return {
+    schema,
+    ...Object.keys(skippedPaths).length > 0 ? { skippedPaths } : {}
+  };
+}
+function toJSONSchema(field, options) {
+  return toJSONSchemaAdvanced(field, options).schema;
 }
 function validateFormanWithDomains(domains, options) {
   return validateFormanWithDomainsInternal(domains, options);
@@ -2205,6 +2292,7 @@ function validateForman(values, schema, options, restoreExtras) {
 export {
   toFormanSchema,
   toJSONSchema,
+  toJSONSchemaAdvanced,
   validateForman,
   validateFormanWithDomains
 };

package/package.json

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