Dynamic JSON Form Renderer

@hzb-rdm/dynamic-json-form-renderer is a reusable React and TypeScript component library for generating accessible, configurable web forms and structured read-only data views from JSON Schema.

It provides a standardized rendering foundation for research metadata applications, including Schema Studio, SEPIA, and other FAIR research data management workflows.

What the software offers

• Generates React forms dynamically from JSON Schema
• Presents stored metadata in a schema-aware, read-only table view
• Uses React JSONSchema Form (RJSF) v6 and AJV validation
• Supports nested objects, arrays, and complex metadata schemas
• Provides accessible validation messages and error summaries
• Supports controlled and uncontrolled form state
• Supports synchronous and asynchronous form submission
• Handles persisted metadata that is no longer allowed by the active schema
• Supports confirmation-based or automatic removal of unsupported fields
• Provides configurable runtime color themes
• Supports light and dark application themes
• Includes reusable widgets and templates based on Shadcn UI
• Detects unresolved JSON Schema references before rendering
• Supports custom RJSF validators, widgets, templates, and UI schemas
• Displays terminology and semantic metadata associated with fields

Terminology-aware metadata

The renderer understands Schema Studio extensions such as:

• x-schema-studio-terminology
• x-schema-studio-suggestions
• x-schema-studio-ui-layout
• x-schema-studio-order

These extensions allow applications to associate form fields with controlled vocabularies, terminology services, concept identifiers, definitions, suggestions, layout information, and display ordering.

Terminology information is available in both editable forms and the schema-aware table view.

Version 2.2.0

Version 2.2.0 introduces safe handling of persisted metadata fields that are no longer permitted by the active JSON Schema.

When a schema defines additionalProperties: false, stored data may contain fields that are no longer valid. The renderer detects these fields, displays their paths in a clear warning, and prevents accidental data loss.

By default, users review the affected fields and confirm their removal before submission. The renderer removes the unsupported fields before validation, allowing the remaining valid metadata to be submitted successfully.

Applications can enable automatic cleanup with omitExtraData:

<DynamicFormRendererGeneric
  schema={schema}
  initialFormData={storedData}
  omitExtraData
  onSubmit={({ formData }) => {
    console.log(formData);
  }}
/>

In this mode, unsupported fields are removed automatically before validation and submission. The warning remains visible so users understand why stored data has changed.

The RJSF liveOmit option is also supported and defaults to false. This means unsupported persisted values are retained while users review or edit the form, unless an application explicitly requests immediate cleanup.

Version 2.2.0 is a backward-compatible minor release. Existing integrations continue to work without changes. Applications may opt into automatic cleanup with omitExtraData; otherwise, the safer confirmation workflow is used.

Schema-aware read-only metadata table

The renderer provides a schema-aware table view for presenting submitted or stored metadata in a structured, read-only format.

The table view supports ordinary form data and versioned metadata envelopes containing schema_name, schema_version, and data.

It provides:

• The showInTable property for DynamicFormRendererGeneric
• The reusable MetadataTableView component
• Recursive rendering of nested objects and arrays
• Full-width sections for nested objects
• Full-width cards for arrays of objects
• Compact and detailed metadata display modes
• Independent expand and collapse controls
• Schema identity information
• Schema-defined field labels and ordering
• Required-field and unit indicators
• Accessible terminology popovers
• Descriptions, types, formats, defaults, constraints, allowed values, and Schema Studio suggestions
• Accessible labels and ARIA attributes for interactive controls

Example

<DynamicFormRendererGeneric
  schema={schema}
  initialFormData={storedData}
  showInTable
  color="blue"
/>

The supplied data can be schema-shaped form data directly or a versioned envelope:

{
  "schema_name": "ElectrodeSample",
  "schema_version": "1.0.1",
  "data": {
    "...": "..."
  }
}

Installation

npm install @hzb-rdm/dynamic-json-form-renderer@2.2.0

Package registry

Add the HZB GitLab package registry to your .npmrc:

@hzb-rdm:registry=https://codebase.helmholtz.cloud/api/v4/packages/npm/

Project information

Source code: https://codebase.helmholtz.cloud/hzb/research_data_management/dynamic-json-form-renderer

npm package: @hzb-rdm/dynamic-json-form-renderer

License: MIT

Dynamic JSON Form Renderer is developed within the Research Data Management activities at Helmholtz-Zentrum Berlin für Materialien und Energie GmbH (HZB) as part of the SEPIA ecosystem for FAIR research metadata management.