feat(types): add advanced field tracking to toJSONSchema#54
Merged
Dominik Kadera (dominikkadera) merged 4 commits intoMay 25, 2026
Merged
Conversation
BREAKING CHANGE: toJSONSchema now returns { schema, skippedPaths? }
instead of a bare JSONSchema7. Fields marked advanced: true are
skipped by default; pass { includeAdvancedFields: true } for previous
behavior. Included advanced fields are stamped with x-advanced: true
and round-trip through toFormanSchema.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Copilot started reviewing on behalf of
Dominik Kadera (dominikkadera)
May 25, 2026 10:26
View session
Contributor
There was a problem hiding this comment.
Pull request overview
This PR introduces a breaking change to the Forman → JSON Schema conversion API by making advanced: true fields omitted by default, while providing opt-in inclusion and reporting skipped paths so callers can request the advanced surface when needed. It also adds round-trip fidelity for advanced fields by stamping included fields with x-advanced: true and teaching toFormanSchema to recover advanced: true from that marker.
Changes:
- Change
toJSONSchemato return{ schema, skippedPaths? }and addFormanJsonSchemaOptions/FormanJsonSchemaResulttypes. - Implement default advanced-field skipping with
skippedPaths.advancedtracking, plusx-advanced: truestamping when advanced fields are included. - Update/migrate tests and snapshots, and add a dedicated advanced-field behavior test suite; bump package version to
2.0.0.
Reviewed changes
Copilot reviewed 27 out of 29 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| test/validator-extended.spec.ts | Formatting-only update; no behavior change. |
| test/test.spec.ts | Migrates to new toJSONSchema(...).schema API and adds round-trip test for advanced: true. |
| test/scenario.spec.ts | Migrates callsites to destructure { schema }. |
| test/redefine.spec.ts | Migrates callsites to destructure { schema }. |
| test/radio.spec.ts | Migrates callsites to destructure { schema } and minor expectation formatting. |
| test/placeholder-nested.spec.ts | Migrates callsites to destructure { schema }. |
| test/nested.spec.ts | Migrates callsites to destructure { schema }. |
| test/list.spec.ts | Migrates callsites to destructure { schema }. |
| test/filestorage.spec.ts | Migrates callsites to destructure { schema }. |
| test/empty-select-option.spec.ts | Migrates callsites to destructure { schema }. |
| test/domains.spec.ts | Migrates callsites to destructure { schema }. |
| test/directives/rpc.spec.ts | Migrates callsites to destructure { schema }. |
| test/directives/nested.spec.ts | Migrates callsites to destructure { schema }. |
| test/directives/grouped.spec.ts | Migrates callsites to destructure { schema }. |
| test/directives/filter.spec.ts | Migrates callsites to destructure { schema }. |
| test/composites/udttype.spec.ts | Migrates callsites to destructure { schema } and updates one test to include advanced fields. |
| test/composites/udtspec.spec.ts | Migrates callsites to destructure { schema } and updates tests to include advanced fields where needed. |
| test/composites/snapshots/udttype.spec.ts.snap | Snapshot updated to include x-advanced: true marker. |
| test/composites/snapshots/udtspec.spec.ts.snap | Snapshot updated to include x-advanced: true marker. |
| test/advanced-fields.spec.ts | New test suite for default advanced skipping, path tracking, and x-advanced stamping behavior. |
| src/types.ts | Adds FormanJsonSchemaOptions and FormanJsonSchemaResult public types. |
| src/json.ts | Wraps toFormanSchema to restore advanced: true from x-advanced: true. |
| src/index.ts | Updates toJSONSchema signature/return type and emits skippedPaths from conversion context. |
| src/forman.ts | Adds includeAdvancedFields/skippedPaths to context and implements advanced filtering at collection insertion point. |
| README.md | Documents breaking change, migration guidance, and new advanced-field behavior. |
| package.json | Bumps version to 2.0.0. |
| package-lock.json | Bumps lockfile package version to 2.0.0. |
| AGENTS.md | Updates internal contributor docs for the new API/options and x-advanced marker. |
| .gitignore | Ignores .claude/*.lock files. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
…dPaths When a composite type (e.g. udtspec) is used multiple times, the addField filter only runs during the first expansion, so only the first usage's path is recorded in skippedPaths.advanced. Subsequent usages share the same definition via $ref and are not re-walked. Documented at the cache site in src/forman.ts and in the corresponding test. Also rewrote the array-with-non-array-spec test as a negative behavior contract: `advanced` on a single-primitive item type has no sibling context to hide from; to hide the array, mark the array field itself. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
… marker framing - README + toJSONSchema JSDoc now scope advanced filtering precisely: applies to collection sub-fields (incl. nested, array-of-collection, composites, cross-domain); does NOT apply to top-level or single- primitive array item types. - AGENTS.md section title corrected: x-* markers are mostly enumerable: true (only x-filestorage is non-enumerable). Renamed "Non-enumerable properties" → "x-* round-trip markers" and explained why defineProperty is used. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Reshape the previous breaking change to ship as a minor (1.14.0):
- Add new toJSONSchemaAdvanced(field, options?) returning
{ schema, skippedPaths? }. toJSONSchema keeps its original bare
JSONSchema7 return shape and now delegates to the new function.
- Flip the default: advanced fields are now INCLUDED by default.
Rename the option to excludeAdvancedFields (default false). Pass
{ excludeAdvancedFields: true } to omit them.
- Included advanced fields still get x-advanced: true on the JSON
Schema and round-trip through toFormanSchema.
- Revert the ~50 test callsite destructurings, drop the now-obsolete
includeAdvancedFields flags from composite tests.
- Rewrite test/advanced-fields.spec.ts around the new model.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Dominik Kadera (dominikkadera)
changed the title
Copilot started reviewing on behalf of
Dominik Kadera (dominikkadera)
May 25, 2026 11:32
View session
Jakub Stok (jakubstokcelonis)
approved these changes
May 25, 2026
Marek Spiska (marekspiska)
approved these changes
May 25, 2026
Dominik Kadera (dominikkadera)
deleted the
dka/advanced-fields-skip-by-default
branch
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Non-breaking minor (v1.14.0) addition for working with Forman fields marked
advanced: true.toJSONSchema(field, options?)continues to return a bareJSONSchema7— fully backward-compatible. Existing callers don't need to change anything.advanced: trueare now stamped withx-advanced: trueon the JSON Schema output, and round-trip throughtoFormanSchema(which restoresadvanced: true).excludeAdvancedFields?: boolean(defaultfalse). Whentrue, advanced sub-fields of a collection are omitted from the schema.toJSONSchemaAdvanced(field, options?)returns{ schema: JSONSchema7, skippedPaths?: { advanced?: string[] } }. Use it when you also need to know which advanced fields were dropped (e.g. to render a "show advanced" toggle).toJSONSchemadelegates to it internally and returns just.schema.Backward compatibility
toJSONSchemareturn typeJSONSchema7(unchanged)toJSONSchemadefault behaviorx-advanced: truestamp on outputJSON.stringify, butx-*is reserved for JSON Schema extensions — practically not breakingtoFormanSchemareadsx-advancedtoJSONSchemaAdvanced,FormanJsonSchemaOptions,FormanJsonSchemaResultexportsImplementation notes
handleCollectionType.addField— a single insertion that uniformly covers main form, nested-by-option fields, array items, RPC param panels, and composite expansions (udtspec/udttype).collectionPathhelper that omits the segment for synthetic anonymous collection wrappers (so[]array paths don't get a literal"undefined"segment).label) are recorded inskippedPathsonce pertoJSONSchemaAdvancedcall, not per usage.toFormanSchemarecoversadvancedfromx-advancedin a top-level wrapper, so all branches (composites, primitives, objects, arrays) inherit it uniformly.Test plan
test/advanced-fields.spec.tscovers: default include +x-advancedstamp, opt-out viaexcludeAdvancedFields,toJSONSchemavstoJSONSchemaAdvancedparity, path correctness (incl. array[]no-undefined), nested-by-option same-level paths, composite filtering, composite cache deduplication, cross-domain buffered fields, required+advanced interaction, top-level always rendered, single-spec array.test/test.spec.tsconfirmsForman → JSON Schema → Formanpreservesadvanced: true.JSONSchema7return shape; no destructuring needed.npm run lintclean,npm test338/338 pass,npm run buildsucceeds.