From 005a446059c5caa63010d76a28e76b8b5933e84c Mon Sep 17 00:00:00 2001 From: Florian Gareis Date: Wed, 16 Jun 2021 15:56:59 +0200 Subject: [PATCH 1/5] Migration guide for version 3.0 --- MIGRATION.md | 69 ++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 9 +++++++ 2 files changed, 78 insertions(+) diff --git a/MIGRATION.md b/MIGRATION.md index 0dfc6fb6b..6bd47a3e4 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -1,3 +1,72 @@ +# Migrating to JSON Forms 3.0 for React users + +With version 3.0 of JSON Forms, we removed the `json-schema-ref-parser` dependency within the core package. +This change only affects users of the React variant (Vue and Angular are not affected) and even for React only a few users will need to adjust their code. +Problematic cases are mostly complex `$ref` setups, often in combination with `anyOf`, `allOf` or `oneOf`. +To restore the previous behavior, you can use `json-schema-ref-parser` or `json-refs` to resolve references on your own before passing the schema to JSON Forms. +Here is an example, how to use these libraries to resolve your refs before handing the schema to JSON Forms: + +```ts +import React, { useState } from 'react'; +import { JsonForms } from '@jsonforms/react'; +import { materialCells, materialRenderers } from '@jsonforms/material-renderers'; +import $RefParser from '@apidevtools/json-schema-ref-parser'; +import JsonRefs from 'JsonRefs'; + +const schema = { + $defs: { + Base: { + type: 'object', + properties: { + width: { + type: 'integer' + } + } + }, + Child: { + type: 'object', + allOf: [ + { $ref: '#/$defs/Base' }, + { + properties: { + geometry: { + type: 'string' + } + } + } + ] + } + }, + type: 'object', + properties: { + element: { + $ref: '#/$defs/Child' + } + } +}; + +const resolvedSchema = $RefParser.dereference(schema) +// or +const resolvedSchema = JsonRefs.resolveRefs(schema) + +function App() { + const [data, setData] = useState(initialData); + + return ( + setData(data)} + /> + ); +} +``` + +For more information have a look at our [ref-resolving](https://jsonforms.io/docs/ref-resolving) docs page. + # Migrating to JSON Forms 2.5 for Angular users The JsonFormsAngularService is not provided in the root anymore. To keep the old behavior, you need to provide it manually in the module. diff --git a/README.md b/README.md index e7f5a3826..a31e1f03b 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,15 @@ Please see the official JSON Forms website, [jsonforms.io](https://jsonforms.io) For more info about the seed app, please see the corresponding README file of the [seed repo](https://github.com/eclipsesource/jsonforms-react-seed). For a more detailed tutorial about the usage of JSON Forms, please see [this tutorial](http://jsonforms.io/docs/tutorial). +## Upgrading to 3.0 + +Within version 3.0 of JSON Forms we removed the `json-schema-ref-parser` dependency from the core package. +This change only affects users of the React variant (Vue and Angular are not affected) and even for React only a few users will need to adjust their code. +If you use ref resolving in combination with `anyOf`, `allOf` or `oneOf`, there could be problems. +To avoid issues and for more information, please have a look at our [migration guide](https://github.com/eclipsesource/jsonforms/blob/master/MIGRATION.md). + +As long as version 3.0 is in alpha stage, we will work on smoothing things out and try to avoid as many issues as possible. + ## Feedback, Help and Support If you encounter any problems feel free to [open an issue](https://github.com/eclipsesource/jsonforms/issues/new/choose) on the repo. From 408e4311c9f255b3da1d4f7a5023b218ce8dfe6b Mon Sep 17 00:00:00 2001 From: Stefan Dirix Date: Thu, 17 Jun 2021 12:36:39 +0200 Subject: [PATCH 2/5] Adapt Text --- MIGRATION.md | 114 +++++++++++++++++++++++++-------------------------- 1 file changed, 57 insertions(+), 57 deletions(-) diff --git a/MIGRATION.md b/MIGRATION.md index 6bd47a3e4..af0eb61ef 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -1,53 +1,33 @@ -# Migrating to JSON Forms 3.0 for React users +# Migration guide + +## Migrating to JSON Forms 3.0 for React users + +With version 3.0 of JSON Forms, we removed the `json-schema-ref-parser` dependency within the core package. +This change only affects users of the React variant, Vue and Angular users are not affected. + +`json-schema-ref-parser` was used to resolve external JSON Schema references. +As a side effect it also resolved 'internal' references and therefore simplified the JSON Schema for JSON Forms' processing. +However that resolving was quite slow, the JSON Schema was mutated in place and `json-schema-ref-parser` brought in Node-only dependencies which needed to be polyfilled. +Also all users of JSON Forms React had to pay the resolving effort, whether they needed it or not. + +Most React users should be unaffected by this change and don't need to spend any migration efforts. +However when you relied on the resolving of external JSON Schema references via the `refParserOptions` or use complicated references setups which can't yet be handled by JSON Forms' internal processing, you can resolve the JSON Schema before handing it over to JSON Forms. + +To restore the old behavior, you can use `json-schema-ref-parser` or other libraries like `json-refs` to resolve references on your own before passing the schema to JSON Forms. -With version 3.0 of JSON Forms, we removed the `json-schema-ref-parser` dependency within the core package. -This change only affects users of the React variant (Vue and Angular are not affected) and even for React only a few users will need to adjust their code. -Problematic cases are mostly complex `$ref` setups, often in combination with `anyOf`, `allOf` or `oneOf`. -To restore the previous behavior, you can use `json-schema-ref-parser` or `json-refs` to resolve references on your own before passing the schema to JSON Forms. -Here is an example, how to use these libraries to resolve your refs before handing the schema to JSON Forms: ```ts import React, { useState } from 'react'; import { JsonForms } from '@jsonforms/react'; import { materialCells, materialRenderers } from '@jsonforms/material-renderers'; import $RefParser from '@apidevtools/json-schema-ref-parser'; -import JsonRefs from 'JsonRefs'; - -const schema = { - $defs: { - Base: { - type: 'object', - properties: { - width: { - type: 'integer' - } - } - }, - Child: { - type: 'object', - allOf: [ - { $ref: '#/$defs/Base' }, - { - properties: { - geometry: { - type: 'string' - } - } - } - ] - } - }, - type: 'object', - properties: { - element: { - $ref: '#/$defs/Child' - } - } -}; +import JsonRefs from 'json-refs'; + +import mySchemaWithReferences from 'myschema.json'; -const resolvedSchema = $RefParser.dereference(schema) +const schema = $RefParser.dereference(mySchemaWithReferences); // or -const resolvedSchema = JsonRefs.resolveRefs(schema) +const schema = JsonRefs.resolveRefs(schemaWithReferences) function App() { const [data, setData] = useState(initialData); @@ -67,8 +47,9 @@ function App() { For more information have a look at our [ref-resolving](https://jsonforms.io/docs/ref-resolving) docs page. -# Migrating to JSON Forms 2.5 for Angular users -The JsonFormsAngularService is not provided in the root anymore. +## Migrating to JSON Forms 2.5 for Angular users + +The JsonFormsAngularService is not provided in the root anymore. To keep the old behavior, you need to provide it manually in the module. The preferred way is using the new JsonForms Component though. @@ -111,7 +92,7 @@ export class AppComponent { } ``` -# Migrating to JSON Forms 2.5 for React users +## Migrating to JSON Forms 2.5 for React users In version 2.5 we made the `redux` dependency within the `react` package optional. Users of the JSON Forms React standalone version (i.e. without Redux) don't need to change anything. @@ -120,6 +101,7 @@ In contrary you no longer need to install 'redux' and 'react-redux' to use JSON Users of the JSON Forms Redux variant need to perform some changes. Basically there are two different approaches: + 1. Migrate your app to the standalone variant 2. Keep using the Redux variant of JSON Forms @@ -129,14 +111,16 @@ In any case, users of the vanilla renderers need to migrate style definitions. Providing style classes via the redux context is no longer supported even when using the redux fallback. For more information see the [vanilla renderer style guide](./packages/vanilla/Styles.md). -## Case 1: Migrate to the standalone variant (recommended) +### Case 1: Migrate to the standalone variant (recommended) The standalone JSON Forms variant is the new default and the main focus for new features and bug fixes. We definitely recommend migrating to this version as soon as possible. All current Redux functionally can also be achieved with the standalone version. -### Example 1: Init action +#### Example 1: Init action + Previously the store was initialized like this: + ```ts const store = createStore( combineReducers({ jsonforms: jsonformsReducer() }), @@ -158,6 +142,7 @@ return ( ``` Instead of creating a store and passing the required information to that store, we rather pass it directly to the `` component: + ```ts return ( ` element like this: + ```ts const renderers = [ ...materialRenderers, @@ -194,7 +182,9 @@ const MyApp = () => ( ); ``` -### Example 3: Listen to data and validation changes + +#### Example 3: Listen to data and validation changes + The `JsonForms` component offers to register a listener which is notified whenever `data` and `errors` changes: ```ts @@ -210,7 +200,7 @@ const MyApp = () => { }; ``` -## Case 2: Use the Redux fallback +### Case 2: Use the Redux fallback If you want to keep using the Redux variant of JSON Forms for now (which is not recommended), you have to change a few import paths. @@ -220,22 +210,26 @@ The new imports are available at `@jsonforms/react/lib/redux`, i.e. import { jsonformsReducer, JsonFormsReduxProvider } from '@jsonforms/react/lib/redux'; ``` -# Migrating from JSON Forms 1.x (AngularJS 1.x) +## Migrating from JSON Forms 1.x (AngularJS 1.x) + The complexity of the migration of an existing JSON Forms 1.x application, which is based on AngularJS, to JSON Forms 2.x depends on the feature set you use. -## Architectural changes in JSON Forms 2.x +### Architectural changes in JSON Forms 2.x + There are two big changes between JSON Forms 1 and JSON Forms 2 you need to understand when migrating your existing application. 1. JSON Forms 2.x does not rely on any specific UI framework [or library]. The `2.0.0` initial release featured renderers based on [React](https://reactjs.org). An [Angular](https://angular.io) based renderer set was released with `2.1.0`. 2. Since JSON Forms 2.x maintains its internal state via [redux](https://redux.js.org/), you will need to add it as a dependency to your application. -## Steps for upgrading your application to JSON Forms 2.x +### Steps for upgrading your application to JSON Forms 2.x + +#### Step 1: Update your UI schemata -### Step 1: Update your UI schemata There is only one minor change in the UI schemata. The UI Schema for controls was simplified and the bulky `ref` object inside `scope` was removed. Instead of: + ```ts const uischema = { type: 'Control', @@ -244,20 +238,26 @@ const uischema = { } } ``` + simply write: + ```ts const uischema = { type: 'Control', scope: '#/properties/name' } ``` + Otherwise the UI schema remains unchanged and works like in JSON Forms 1.x. -### Step 2: Use JSON Forms 2.x in your application +#### Step 2: Use JSON Forms 2.x in your application + As JSON Forms 2 does not rely on any specific UI framework or library you can choose which renderer set you want to use. The React Material renderer set is the most polished one at the moment, followed by Angular Material and the Vanilla renderer sets. -#### Use with React -Please refer to the React [Tutorial](http://jsonforms.io/docs/tutorial). +##### Use with React + +Please refer to the React [tutorial](http://jsonforms.io/docs/tutorial). + +#### Step 3: Migrate Custom Renderers -### Step 3: Migrate Custom Renderers Any custom renderer needs to be re-factored to conform to the new custom renderer style in JSON Forms 2.x. You can find instructions how to implement Custom controls based on React [here](http://jsonforms.io/docs/custom-renderers). While you need to change a lot except for the template, the good news it that writing custom renderers became much simpler in JSON Forms 2 since the framework will trigger rendering and re-rendering in case of changes to the data or other state. In many cases this means you will be able to streamline your code for custom renderers significantly. From 2f8fbf578e16ef551b0bd86bd34d8f2f5185d29d Mon Sep 17 00:00:00 2001 From: Florian Gareis Date: Thu, 17 Jun 2021 16:31:16 +0200 Subject: [PATCH 3/5] Update example --- MIGRATION.md | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/MIGRATION.md b/MIGRATION.md index af0eb61ef..7017c960f 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -25,12 +25,25 @@ import JsonRefs from 'json-refs'; import mySchemaWithReferences from 'myschema.json'; -const schema = $RefParser.dereference(mySchemaWithReferences); -// or -const schema = JsonRefs.resolveRefs(schemaWithReferences) +const refParserOptions = { + dereference: { + circular: false + } +} function App() { const [data, setData] = useState(initialData); + const [resolvedSchema, setSchema] = useState(); + + useEffect(() => { + $RefParser.dereference(mySchemaWithReferences).then(res => setSchema(res.$schema)); + // or + JsonRefs.resolveRefs(mySchemaWithReferences).then(res => setSchema(res.resolved)); + },[]); + + if(resolvedSchema === undefined) { + return
Loading...
+ } return ( Date: Fri, 18 Jun 2021 17:03:53 +0200 Subject: [PATCH 4/5] Update text --- MIGRATION.md | 5 ++++- README.md | 9 +++------ 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/MIGRATION.md b/MIGRATION.md index 7017c960f..1b42bee50 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -13,8 +13,11 @@ Also all users of JSON Forms React had to pay the resolving effort, whether they Most React users should be unaffected by this change and don't need to spend any migration efforts. However when you relied on the resolving of external JSON Schema references via the `refParserOptions` or use complicated references setups which can't yet be handled by JSON Forms' internal processing, you can resolve the JSON Schema before handing it over to JSON Forms. -To restore the old behavior, you can use `json-schema-ref-parser` or other libraries like `json-refs` to resolve references on your own before passing the schema to JSON Forms. +Note that we're aware of some regressions caused by removing `json-schema-ref-parser` which occur when not handing over a resolved JSON Schema to JSON Forms. +We're working on removing these edge cases during the JSON Forms 3.0 alpha period. +You can always restore the old behavior when following the approach described below. +To restore the old behavior, you can use `json-schema-ref-parser` or other libraries like `json-refs` to resolve references on your own before passing the schema to JSON Forms. ```ts import React, { useState } from 'react'; diff --git a/README.md b/README.md index a31e1f03b..2160026b6 100644 --- a/README.md +++ b/README.md @@ -15,14 +15,11 @@ Please see the official JSON Forms website, [jsonforms.io](https://jsonforms.io) For more info about the seed app, please see the corresponding README file of the [seed repo](https://github.com/eclipsesource/jsonforms-react-seed). For a more detailed tutorial about the usage of JSON Forms, please see [this tutorial](http://jsonforms.io/docs/tutorial). -## Upgrading to 3.0 +## Upgrading to JSON Forms 3.0 -Within version 3.0 of JSON Forms we removed the `json-schema-ref-parser` dependency from the core package. +With version 3.0 of JSON Forms we removed the `json-schema-ref-parser` from the core package. This change only affects users of the React variant (Vue and Angular are not affected) and even for React only a few users will need to adjust their code. -If you use ref resolving in combination with `anyOf`, `allOf` or `oneOf`, there could be problems. -To avoid issues and for more information, please have a look at our [migration guide](https://github.com/eclipsesource/jsonforms/blob/master/MIGRATION.md). - -As long as version 3.0 is in alpha stage, we will work on smoothing things out and try to avoid as many issues as possible. +To avoid issues and for more information, please have a look at our [migration guide](https://github.com/eclipsesource/jsonforms/blob/master/MIGRATION.md). ## Feedback, Help and Support From e25ad752613b1507dca402150fd65ab94a6d2e34 Mon Sep 17 00:00:00 2001 From: Stefan Dirix Date: Fri, 18 Jun 2021 17:07:17 +0200 Subject: [PATCH 5/5] adapt text --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 2160026b6..7c707650e 100644 --- a/README.md +++ b/README.md @@ -15,9 +15,9 @@ Please see the official JSON Forms website, [jsonforms.io](https://jsonforms.io) For more info about the seed app, please see the corresponding README file of the [seed repo](https://github.com/eclipsesource/jsonforms-react-seed). For a more detailed tutorial about the usage of JSON Forms, please see [this tutorial](http://jsonforms.io/docs/tutorial). -## Upgrading to JSON Forms 3.0 +## Upgrading to JSON Forms 3.0 Alpha -With version 3.0 of JSON Forms we removed the `json-schema-ref-parser` from the core package. +With version 3.0 of JSON Forms we removed `json-schema-ref-parser` from the core package. This change only affects users of the React variant (Vue and Angular are not affected) and even for React only a few users will need to adjust their code. To avoid issues and for more information, please have a look at our [migration guide](https://github.com/eclipsesource/jsonforms/blob/master/MIGRATION.md).