Migration guide for version 3.0

Author: TheZoker

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 (
+    <JsonForms
+      schema={resolvedSchema}
+      uischema={uischema}
+      data={data}
+      renderers={materialRenderers}
+      cells={materialCells}
+      onChange={({ data, _errors }) => 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.

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.