@makehq/forman-schema 1.13.2 → 1.14.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

package/dist/index.cjs

@@ -22,6 +22,7 @@ var index_exports = {};
 __export(index_exports, {
   toFormanSchema: () => toFormanSchema,
   toJSONSchema: () => toJSONSchema,
+  toJSONSchemaAdvanced: () => toJSONSchemaAdvanced,
   validateForman: () => validateForman,
   validateFormanWithDomains: () => validateFormanWithDomains
 });
@@ -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.");
     }
@@ -695,6 +698,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 +711,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"]) {
@@ -2074,6 +2091,13 @@ 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) {
   const compositeType = Object.getOwnPropertyDescriptor(field, "x-composite")?.value;
   if (compositeType === "udttype") return udttypeCollapse(field);
   if (compositeType === "udtspec") return udtspecCollapse(field);
@@ -2209,18 +2233,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 +2269,7 @@ function validateForman(values, schema, options, restoreExtras) {
 0 && (module.exports = {
   toFormanSchema,
   toJSONSchema,
+  toJSONSchemaAdvanced,
   validateForman,
   validateFormanWithDomains
 });

package/dist/index.d.cts

@@ -222,6 +222,30 @@ 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[];
+    };
+};
 type FormanValidationOptions = {
     /** Unknown fields are not allowed when strict is true */
     strict?: boolean;
@@ -246,12 +270,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 +334,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 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

@@ -222,6 +222,30 @@ 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[];
+    };
+};
 type FormanValidationOptions = {
     /** Unknown fields are not allowed when strict is true */
     strict?: boolean;
@@ -246,12 +270,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 +334,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 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

@@ -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.");
     }
@@ -666,6 +668,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 +681,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"]) {
@@ -2045,6 +2061,13 @@ 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) {
   const compositeType = Object.getOwnPropertyDescriptor(field, "x-composite")?.value;
   if (compositeType === "udttype") return udttypeCollapse(field);
   if (compositeType === "udtspec") return udtspecCollapse(field);
@@ -2180,18 +2203,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 +2238,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.14.0",
     "description": "Forman Schema Tools",
     "license": "MIT",
     "author": "Make",