JSON Forms Documentation

repository·master·Indexed 25 days ago

https://github.com/eclipsesource/jsonforms

A library for creating complex forms using JSON Schema and UI Schema. It provides a core engine (@jsonforms/core) and supports multiple UI frameworks including React (@jsonforms/react), Angular (@jsonforms/angular), and Vue (@jsonforms/vue), with available renderer sets such as Material Design and Vanilla renderers.

Tokens
32.8K
Snippets
50
Records
224
Agent score
81%

What's inside JSON Forms

  1. Overview of JSON Forms Core

    master
    JSON Forms is a library designed to eliminate the manual effort of writing complex forms by leveraging JSON, JSON Schema, and JavaScript. The @jsonforms/core package provides the fundamental logic and functionality required to render forms, but it does not include UI components directly. To render forms, you must pair the core package with a UI framework-specific package.
  2. Migrate Translator usage in JSON Forms 3.8

    master

    In JSON Forms 3.8, the Translator type changed from overloaded signatures to a generic conditional type to improve TypeScript compatibility.

    Direct assignment: You can no longer assign a function directly to the Translator type. Use the createTranslator helper from @jsonforms/core instead.

    Vue Options API: If you use custom Vue renderers that access a Translator via this (Options API), the return type might not narrow to string automatically due to Vue's ref unwrapping. Use as string when a default message is guaranteed to be provided.

  3. Handle JSON Schema Reference Resolution in React (JSON Forms 3.0+)

    master

    JSON Forms 3.0 removed the internal json-schema-ref-parser dependency from the core package. This affects React users who rely on the automatic resolution of external JSON Schema references.

    If your schemas use external references that JSON Forms cannot resolve internally, you must resolve them manually using a library like @apidevtools/json-schema-ref-parser or json-refs before passing the schema to the JsonForms component.

    import React, { useState, useEffect } from 'react';
    import { JsonForms } from '@jsonforms/react';
    import { materialCells, materialRenderers } from '@jsonforms/material-renderers';
    import $RefParser from '@apidevtools/json-schema-ref-parser';
    
    function App() {
      const [resolvedSchema, setResolvedSchema] = useState();
    
      useEffect(() => {
        $RefParser.dereference(mySchemaWithReferences).then((res) => setResolvedSchema(res.$schema));
      }, []);
    
      if (resolvedSchema === undefined) return <div>Loading...</div>;
    
      return (
        <JsonForms
          schema={resolvedSchema}
          uischema={uischema}
          data={data}
          renderers={materialRenderers}
          cells={materialCells}
          onChange={({ data }) => setData(data)}
        />
      );
    }
  4. Get started with the JSON Forms React seed app

    master

    To quickly explore JSON Forms using a pre-configured React application, clone the seed repository and run it locally.

    1. Clone the seed app: git clone https://github.com/eclipsesource/jsonforms-react-seed.git
    2. Install dependencies: npm ci
    3. Start the application: npm run start
    git clone https://github.com/eclipsesource/jsonforms-react-seed.git
    npm ci
    npm run start
  5. Use Redux fallback for React (v2.5+)

    master

    If you cannot migrate to the standalone variant immediately, you must update your import paths to use the Redux fallback located at @jsonforms/react/lib/redux.

    import {
      jsonformsReducer,
      JsonFormsReduxProvider,
    } from '@jsonforms/react/lib/redux';
  6. Migrate Custom Renderers from JSON Forms 1.x to 2.x

    master
    Custom renderers from version 1.x must be refactored to conform to the new style in 2.x. While the template logic may remain similar, the framework now handles rendering and re-rendering automatically when data or state changes, allowing for much simpler implementation.
  7. Configure Vite for @jsonforms/vue-vuetify

    master

    When using Vite, you must exclude vuetify from optimizeDeps to avoid a TypeError: makeVExpansionPanelTextProps is not a function error during development.

    // https://vitejs.dev/config/
    export default defineConfig({
      optimizeDeps: {
        // Exclude vuetify since it has an issue with vite dev - TypeError: makeVExpansionPanelTextProps is not a function - the makeVExpansionPanelTextProps is used before it is defined
        exclude: ['vuetify'],
      },
    
      // more config....
    });
  8. Migrate UI Schemata from JSON Forms 1.x to 2.x

    master

    When upgrading from version 1.x, the UI Schema for controls has been simplified. The ref object inside the scope property has been removed. You should now provide the $ref string directly to scope.

    // Old (1.x)
    const uischema = {
      type: 'Control',
      scope: {
        $ref: '#/properties/name',
      },
    };
    
    // New (2.x)
    const uischema = {
      type: 'Control',
      scope: '#/properties/name',
    };
  9. Create a custom Control renderer

    master

    To create a custom control renderer, use the rendererProps factory to declare required props and a binding like useJsonFormsControl in the setup function. The binding provides a control object containing attributes like data, description, errors, and enabled, as well as a handleChange(path, value) method to update data.

    Example implementation:

    import { ControlElement } from '@jsonforms/core';
    import { defineComponent } from 'vue';
    import { rendererProps, useJsonFormsControl } from '@jsonforms/vue';
    
    const controlRenderer = defineComponent({
      name: 'control-renderer',
      props: {
        ...rendererProps<ControlElement>(),
      },
      setup(props) {
        return useJsonFormsControl(props);
      },
      methods: {
        onChange(event: Event) {
          this.handleChange(
            this.control.path,
            (event.target as HTMLInputElement).value
          );
        },
      },
    });
    export default controlRenderer;
  10. Run specific renderer examples

    master

    You can run development servers for specific renderer implementations by navigating to their respective packages:

    • React Vanilla: cd packages/vanilla-renderers && pnpm run dev
    • React Material: cd packages/material-renderers && pnpm run dev
    • Angular Material: cd packages/angular-material && pnpm run dev
    • Vue Vanilla: cd packages/vue-vanilla && pnpm run dev
    • Vue Vuetify: cd packages/vue-vuetify && pnpm run dev