Unify path handling to consistenly use JSON Pointer

MIGRATION.md

@@ -1,5 +1,121 @@
 # Migration guide
 
+## Migrating to JSON Forms 4.0
+
+### Unified internal path handling to JSON pointers
+
+Previously, JSON Forms used two different ways to express paths:
+
+- The `scope` JSON Pointer (see [RFC 6901](https://datatracker.ietf.org/doc/html/rfc6901)) paths used in UI Schemas to resolve subschemas of the provided JSON Schema
+- The dot-separated paths (lodash format) to resolve entries in the form-wide data object
+
+This led to confusion and prevented property names from containing dots (`.`) because lodash paths don't support escaping.
+
+The rework unifies these paths to all use the JSON Pointer format.
+Therefore, this breaks custom renderers that manually modify or create paths to resolve additional data.
+They used the dot-separated paths and need to be migrated to use JSON Pointers instead.
+
+To abstract the composition of paths away from renderers, the `Paths.compose` utility of `@jsonforms/core` should be used.
+It takes a valid JSON Pointer and an arbitrary number of _unencoded_ segments to append.
+The utility takes care of adding separators and encoding special characters in the given segments.
+
+#### How to migrate
+
+All paths that are manually composed or use the `Paths.compose` utility and add more than one segment need to be adapted.
+
+```ts
+import { Paths } from '@jsonforms/core';
+
+// Some base path we want to extend. This is usually available in the renderer props
+// or the empty string for the whole data object
+const path = '/foo'
+
+// Previous: Calculate the path manually
+const oldManual = `${path}.foo.~bar`;
+// Previous: Use the Paths.compose util
+const oldWithUtil = Paths.compose(path, 'foo.~bar');
+
+// Now: After the initial path, hand in each segment separately.
+// Segments must be unencoded. The util automatically encodes them.
+// In this case the ~ will be encoded.
+const new = Paths.compose(path, 'foo', '~bar');
+
+// Calculate a path relative to the root data that the path is resolved against
+const oldFromRoot = 'nested.prop';
+const newFromRoot = Paths.compose('', 'nested', 'prop'); // The empty JSON Pointer '' points to the whole data.
+```
+
+#### Custom Renderer Example
+
+This example shows in a more elaborate way, how path composition might be used in a custom renderer.
+This example uses a custom renderer implemented for the React bindings.
+However, the approach is similar for all bindings.
+
+To showcase how a migration could look like, assume a custom renderer that gets handed in this data object:
+
+```ts
+const data = {
+  foo: 'abc',
+  'b/ar': {
+    '~': 'tilde',
+  },
+  'array~Data': ['entry1', 'entry2'],
+};
+```
+
+The renderer wants to resolve the `~` property to directly use it and iterate over the array and use the dispatch to render each entry.
+
+<details>
+<summary>Renderer code</summary>
+
+```tsx
+import { Paths, Resolve } from '@jsonforms/core';
+import { JsonFormsDispatch } from '@jsonforms/react';
+
+export const CustomRenderer = (props: ControlProps & WithInput) => {
+  const {
+    // [...]
+    data, // The data object to be rendered. See content above
+    path, // Path to the data object handed into this renderer
+    schema, // JSON Schema describing this renderers data
+  } = props;
+
+  // Calculate path from the given data to the nested ~ property
+  // You could also do this manually without the Resolve.data util
+  const tildePath = Paths.compose('', 'b/ar', '~');
+  const tildeValue = Resolve.data(data, tildePath);
+
+  const arrayData = data['array~Data'];
+  // Resolve schema of array entries from this renderer's schema.
+  const entrySchemaPath = Paths.compose(
+    '#',
+    'properties',
+    'array~Data',
+    'items'
+  );
+  const entrySchema = Resolve.schema(schema, entrySchemaPath);
+  // Iterate over array~Data and dispatch for each entry
+  // Dispatch needs the path from the root of JSON Forms's data
+  // Thus, calculate it by extending this control's path
+  const dispatchEntries = arrayData.map((arrayEntry, index) => {
+    const entryPath = Paths.compose(path, 'array~Data', index);
+    const schema = Resolve.schema();
+    return (
+      <JsonFormsDispatch
+        key={index}
+        schema={entrySchema}
+        path={path}
+        // [...] other props like cells, etc
+      />
+    );
+  });
+
+  // [...]
+};
+```
+
+</details>
+
 ## Migrating to JSON Forms 3.3
 
 ### Angular support now targets Angular 17 and Angular 18

packages/angular-material/src/library/layouts/array-layout.renderer.ts

@@ -243,7 +243,7 @@ export class ArrayLayoutRenderer
     }
     return {
       schema: this.scopedSchema,
-      path: Paths.compose(this.propsPath, `${index}`),
+      path: Paths.compose(this.propsPath, index),
       uischema,
     };
   }

packages/angular-material/src/library/other/master-detail/master.ts

@@ -48,6 +48,7 @@ import {
   JsonFormsState,
   mapDispatchToArrayControlProps,
   mapStateToArrayControlProps,
+  Paths,
   RankedTester,
   rankWith,
   setReadonly,
@@ -94,7 +95,7 @@ export const removeSchemaKeywords = (path: string) => {
             <button
               mat-icon-button
               class="button item-button hide"
-              (click)="onDeleteClick(i)"
+              (click)="onDeleteClick($event, i)"
               [ngClass]="{ show: highlightedIdx == i }"
               *ngIf="isEnabled()"
             >
@@ -229,7 +230,7 @@ export class MasterListComponent
           ? d.toString()
           : get(d, labelRefInstancePath ?? getFirstPrimitiveProp(schema)),
         data: d,
-        path: `${path}.${index}`,
+        path: Paths.compose(path, index),
         schema,
         uischema: detailUISchema,
       };
@@ -283,7 +284,8 @@ export class MasterListComponent
     )();
   }
 
-  onDeleteClick(item: number) {
+  onDeleteClick(e: any, item: number) {
+    e.stopPropagation();
     this.removeItems(this.propsPath, [item])();
   }
 

packages/angular-material/src/library/other/table.renderer.ts

@@ -34,7 +34,6 @@ import {
   ControlElement,
   createDefaultValue,
   deriveTypes,
-  encode,
   isObjectArrayControl,
   isPrimitiveArrayControl,
   JsonSchema,
@@ -211,8 +210,9 @@ export class TableRenderer extends JsonFormsArrayControl implements OnInit {
   ): ColumnDescription[] => {
     if (schema.type === 'object') {
       return this.getValidColumnProps(schema).map((prop) => {
-        const encProp = encode(prop);
-        const uischema = controlWithoutLabel(`#/properties/${encProp}`);
+        const uischema = controlWithoutLabel(
+          Paths.compose('#', 'properties', prop)
+        );
         if (!this.isEnabled()) {
           setReadonly(uischema);
         }
@@ -275,7 +275,7 @@ export const controlWithoutLabel = (scope: string): ControlElement => ({
 @Pipe({ name: 'getProps' })
 export class GetProps implements PipeTransform {
   transform(index: number, props: OwnPropsOfRenderer) {
-    const rowPath = Paths.compose(props.path, `${index}`);
+    const rowPath = Paths.compose(props.path, index);
     return {
       schema: props.schema,
       uischema: props.uischema,

packages/angular-material/test/master-detail.spec.ts

@@ -223,7 +223,7 @@ describe('Master detail', () => {
     // delete 1st item
     spyOn(component, 'removeItems').and.callFake(() => () => {
       getJsonFormsService(component).updateCore(
-        Actions.update('orders', () => moreData.orders.slice(1))
+        Actions.update('/orders', () => moreData.orders.slice(1))
       );
       fixture.detectChanges();
     });
@@ -267,7 +267,7 @@ describe('Master detail', () => {
       const copy = moreData.orders.slice();
       copy.splice(1, 1);
       getJsonFormsService(component).updateCore(
-        Actions.update('orders', () => copy)
+        Actions.update('/orders', () => copy)
       );
       fixture.detectChanges();
     });
@@ -382,7 +382,7 @@ describe('Master detail', () => {
               customer: { name: 'ACME' },
               title: 'Carrots',
             },
-            path: 'orders.0',
+            path: '/orders/0',
             schema: schema.definitions.order,
             uischema: {
               type: 'VerticalLayout',

packages/core/src/i18n/i18nUtil.ts

@@ -13,6 +13,7 @@ import {
   formatErrorMessage,
   getControlPath,
   isInternationalized,
+  toLodashPath,
 } from '../util';
 
 export const getI18nKeyPrefixBySchema = (
@@ -31,7 +32,7 @@ export const getI18nKeyPrefixBySchema = (
  */
 export const transformPathToI18nPrefix = (path: string): string => {
   return (
-    path
+    toLodashPath(path)
       ?.split('.')
       .filter((segment) => !/^\d+$/.test(segment))
       .join('.') || 'root'

packages/core/src/mappers/renderer.ts

@@ -713,7 +713,7 @@ export const mapStateToMasterListItemProps = (
   ownProps: OwnPropsOfMasterListItem
 ): StatePropsOfMasterItem => {
   const { schema, path, uischema, childLabelProp, index } = ownProps;
-  const childPath = composePaths(path, `${index}`);
+  const childPath = composePaths(path, index);
   const childLabel = computeChildLabel(
     getData(state),
     childPath,

packages/core/src/reducers/core.ts

@@ -45,7 +45,7 @@ import {
 import { JsonFormsCore, Reducer, ValidationMode } from '../store';
 import Ajv, { ErrorObject } from 'ajv';
 import { isFunction } from 'lodash';
-import { createAjv, validate } from '../util';
+import { createAjv, toLodashSegments, validate } from '../util';
 
 export const initState: JsonFormsCore = {
   data: {},
@@ -237,18 +237,19 @@ export const coreReducer: Reducer<JsonFormsCore, CoreActions> = (
           errors,
         };
       } else {
-        const oldData: any = get(state.data, action.path);
+        const lodashDataPathSegments = toLodashSegments(action.path);
+        const oldData: any = get(state.data, lodashDataPathSegments);
         const newData = action.updater(cloneDeep(oldData));
         let newState: any;
         if (newData !== undefined) {
           newState = setFp(
-            action.path,
+            lodashDataPathSegments,
             newData,
             state.data === undefined ? {} : state.data
           );
         } else {
           newState = unsetFp(
-            action.path,
+            lodashDataPathSegments,
             state.data === undefined ? {} : state.data
           );
         }

packages/core/src/reducers/i18n.ts

@@ -31,7 +31,10 @@ import {
   UPDATE_I18N,
 } from '../actions';
 import { Reducer } from '../store/type';
-import { JsonFormsI18nState } from '../store';
+import { ErrorTranslator, JsonFormsI18nState, Translator } from '../store';
+import { UISchemaElement } from '../models';
+import { toLodashPath } from '../util';
+import { ErrorObject } from 'ajv';
 
 export const defaultJsonFormsI18nState: Required<JsonFormsI18nState> = {
   locale: 'en',
@@ -50,7 +53,6 @@ export const i18nReducer: Reducer<JsonFormsI18nState, I18nActions> = (
         action.translator ?? defaultJsonFormsI18nState.translate;
       const translateError =
         action.errorTranslator ?? defaultJsonFormsI18nState.translateError;
-
       if (
         locale !== state.locale ||
         translate !== state.translate ||
@@ -80,3 +82,19 @@ export const i18nReducer: Reducer<JsonFormsI18nState, I18nActions> = (
       return state;
   }
 };
+
+export const wrapTranslateFunction = (translator: Translator): Translator => {
+  return (id: string, defaultMessage?: string | undefined, values?: any) => {
+    return translator(toLodashPath(id), defaultMessage, values);
+  };
+};
+
+export const wrapErrorTranslateFunction = (
+  translator: ErrorTranslator
+): ErrorTranslator => {
+  return (
+    error: ErrorObject,
+    translate: Translator,
+    uischema?: UISchemaElement
+  ) => translator(error, wrapTranslateFunction(translate), uischema);
+};

packages/core/src/store/jsonFormsCore.ts

@@ -34,7 +34,7 @@ export const errorAt = (instancePath: string, schema: JsonSchema) =>
   getErrorsAt(instancePath, schema, (path) => path === instancePath);
 export const subErrorsAt = (instancePath: string, schema: JsonSchema) =>
   getErrorsAt(instancePath, schema, (path) =>
-    path.startsWith(instancePath + '.')
+    path.startsWith(instancePath + '/')
   );
 
 export const getErrorAt =

packages/core/src/util/errors.ts

@@ -24,7 +24,7 @@
 */
 
 import { ErrorObject } from 'ajv';
-import { decode } from './path';
+import { composePaths } from './path';
 import { JsonSchema } from '../models';
 import { isOneOfEnumSchema } from './schema';
 import filter from 'lodash/filter';
@@ -47,19 +47,11 @@ export const getControlPath = (error: ErrorObject) => {
   // With AJV v8 the property was renamed to 'instancePath'
   let controlPath = (error as any).dataPath || error.instancePath || '';
 
-  // change '/' chars to '.'
-  controlPath = controlPath.replace(/\//g, '.');
-
   const invalidProperty = getInvalidProperty(error);
   if (invalidProperty !== undefined && !controlPath.endsWith(invalidProperty)) {
-    controlPath = `${controlPath}.${invalidProperty}`;
+    controlPath = composePaths(controlPath, invalidProperty);
   }
 
-  // remove '.' chars at the beginning of paths
-  controlPath = controlPath.replace(/^./, '');
-
-  // decode JSON Pointer escape sequences
-  controlPath = decode(controlPath);
   return controlPath;
 };