JSON Schema

[thorwhalen]

Notes on JSON schema.

[thorwhalen]

Intellisense enablement

The integration of Intellisense or auto-completion features into JSON editing workflows significantly enhances the user experience by providing real-time feedback, validation, and suggestions while editing JSON documents. A standardized way to achieve this is through the use of JSON Schema, a powerful tool for specifying and validating the structure of JSON data.

JSON Schema is a vocabulary that allows you to annotate and validate JSON documents. It describes the structure of the data, the data types of each field, the presence of required fields, and even complex constraints like dependencies and pattern matching. By defining a JSON Schema, you effectively communicate the expected structure of the JSON data, enabling editors that support JSON Schema to offer suggestions, auto-completion, and validation against the schema.

Here's how the process generally works:

1. Define a JSON Schema: The first step is to define a JSON Schema for your JSON data format. This schema outlines what properties are available, their data types (such as string, integer, boolean), enumeration of possible values for certain fields, and any required properties. The schema itself is written in JSON, making it both human-readable and machine-interpretable.

2. Associate the JSON Schema with JSON Documents: After defining the schema, the next step is to associate it with your JSON documents. This can be done in several ways, depending on the environment and the editor you are using. Some editors and IDEs (Integrated Development Environments) allow you to specify the schema within the JSON document itself using a $schema property, or you can configure the editor to use a specific schema for files matching certain patterns.

3. Editing with Intellisense: With the schema defined and associated with your JSON documents, compatible JSON editors can now provide Intellisense features. As you edit the JSON documents, the editor can offer:

   • Auto-completion: Suggest property names and value enumerations defined in the schema.
   • Tooltips: Show descriptions for properties and values if they are included in the schema.
   • Validation: Provide real-time feedback if the edited JSON does not conform to the schema, such as when required properties are missing or when data types do not match.

Several popular editors and IDEs support JSON Schema, including Visual Studio Code, WebStorm, Atom, and others. For Visual Studio Code, for example, there are extensions and built-in features that automatically leverage JSON Schema for files based on their filename patterns or if the $schema keyword is present in the document.

JSON Schema also supports more complex scenarios, including extending existing schemas, referencing external schemas, and defining conditional schema application based on the data. This flexibility makes it a robust solution for managing JSON data structures across a wide range of applications and services.

In summary, by leveraging JSON Schema, developers can provide a rich editing experience that enhances productivity, reduces errors, and ensures data consistency across JSON-based configurations, data exchanges, and APIs.

[thorwhalen]

JSON editors

Many features of my application boils down to having my users edit a nested structure -- which I represent as JSON. These JSONs will always have a schema associated with them, and I'd like to use a "JSON editor" that makes it really easy for the user to produce valid JSONs within that schema. What ReactJS packages/tools/components would you suggest I look into?

For applications that necessitate users to edit nested JSON structures within the constraints of a predefined schema, leveraging a robust JSON editor component is essential for ensuring that users can efficiently produce valid JSON documents. In the React ecosystem, there are several packages and components designed specifically for this purpose, integrating seamlessly with JSON Schema to offer a user-friendly interface for JSON editing. Below are some of the most recommended React packages and tools for implementing a JSON editor with schema validation:

Here are some that are more like what you would think of as "json editors" (text editor that is aware that it's json it's editing).
I don't know if any of them are able to use a json schema to got further (namely, offer validation feedback).

Editors

A. react-simple-code-editor

• Description: The react-simple-code-editor is a streamlined, no-frills code editor focusing on simplicity and minimalism. It distinguishes itself by providing just enough functionality for code editing with syntax highlighting, without the overhead of more feature-rich editors. This makes it particularly suited for embedding a straightforward code editor in web pages or forms where users submit code snippets.

• Features:

  • The editor is modular, allowing for syntax highlighting through integration with third-party libraries.
  • Supports indenting of lines or selected text using the tab key, with customizable indentation levels.
  • Features automatic indentation on new lines and allows for wrapping selected text in various brackets or quotes.
  • Offers an undo feature that operates on whole words rather than individual letters.
  • It is designed to be accessible, including a shortcut (Ctrl+Shift+M on Mac and Ctrl+M on other systems) to toggle capturing the tab key.

• Use Case: react-simple-code-editor is ideal for applications requiring a straightforward code input mechanism without the need for extensive features provided by more comprehensive code editors. Its lightweight nature and ease of use make it perfect for simple embeds, such as forms where users are expected to submit code, or for educational tools where simplicity and ease of setup are key priorities.

This editor works by overlaying a syntax-highlighted <pre> block over a <textarea>. Users interact with the <textarea>, ensuring that the typing and selection experience feels native. The approach is simpler compared to full-featured code editors that might re-implement text input behaviors from scratch. Due to its implementation method, it maintains compatibility with modern browsers but has certain limitations, such as uniform styling across the syntax-highlighted code and performance considerations for large documents.

See: npmjs.com, snyk.io, libraries.io.

B. react-json-editor-ajrm

• Description: This package offers a customizable JSON editor with syntax highlighting and error checking. It doesn't directly integrate with JSON Schema for validation but provides an easy-to-use interface for editing JSON text.
• Features: Syntax highlighting, error detection, and a customizable interface. While it doesn’t validate against a JSON Schema out of the box, it can be combined with additional validation logic to enforce schema constraints.
• Use Case: Suitable for applications where developers prefer to work directly with JSON text and are comfortable implementing additional schema validation logic.

Form makers

The next ones can still be used as json editors in a sense, but the way things are viewed is more form-like.
This is very useful in some contexts, but can lead to visual overload in others.

1. react-jsonschema-form (rjsf)

See this great rjsf playground (fiddle)

• Description: This library is built by Mozilla and provides a straightforward way to generate a form interface from a JSON Schema. It supports custom form widgets, validation, and has a pluggable system for advanced customization.
• Features: It automatically generates form inputs for each of the schema's properties, handles data validation according to the schema, and provides a simple way to customize form layout and UI components.
• Use Case: Ideal for applications requiring forms to collect or edit structured data, which is then output as validated JSON.

2. @rjsf/core

• Description: Formerly known as react-jsonschema-form, this is the core package of the React JSON Schema Form ecosystem, allowing the creation of React forms based on a JSON Schema.
• Features: It supports custom themes, widgets, and is extendable. The package is part of a larger ecosystem, including libraries for material-ui, bootstrap, and other UI frameworks.
• Use Case: Perfect for those who want the flexibility of react-jsonschema-form with the added ability to swap out UI themes or deeply customize the form behavior.

3. JSONForms

• Description: Developed by EclipseSource, JSONForms leverages JSON Schema and provides a high degree of flexibility and customization. It abstracts away the tedious task of implementing form rendering logic, instead focusing on binding the UI to the schema.
• Features: It supports complex schemas with conditions, nested objects, and arrays. JSONForms is highly customizable, allowing developers to define how different parts of the schema should be rendered using custom components.
• Use Case: Ideal for complex applications that require extensive customization and have sophisticated form rendering needs beyond simple key-value editing.

4. formik-json-schema

See demo.

• Description: A lightweight wrapper around Formik, one of the most popular form libraries in the React ecosystem, enabling the creation of form UIs based on a given JSON Schema.
• Features: Leverages Formik's power and flexibility, including its handling of form state, validation, and submission, translating JSON Schema into Formik-compatible configurations.
• Use Case: Best for developers already familiar with Formik looking to integrate JSON Schema-based form generation without sacrificing the control and customizability that Formik provides.

[thorwhalen]

Controlling JSON CRUD

I'd like to be able to associate various access characteristics to my json fields (possibly nested). For example:

• Not showing the field at all
• Showing it, but without having allowing it to be edited
• Showing it and allowing it to be edited.

How would I do this using react-jsonschema-form, and if not possible with that package, how can I use a different package for this purpose?

To manage various access characteristics for JSON fields, such as visibility, editability, and complete interaction control, react-jsonschema-form (RJSF) offers a flexible solution through the use of custom widgets, UI schemas, and conditional logic within the JSON Schema definition itself. Here's how you can implement the desired access characteristics using RJSF:

1. Not Showing the Field at All

You can use the uiSchema to hide fields conditionally based on the application logic. However, RJSF doesn't directly support conditional rendering in the uiSchema. You would typically manage this by dynamically modifying the schema or uiSchema passed to the RJSF based on the conditions you want to apply.

Alternatively, to simply not render a field, you might exclude it from the schema or use a custom widget that renders nothing.

2. Showing It, But Without Having It to Be Edited

RJSF supports read-only fields through the uiSchema. You can mark a field as read-only using the ui:readonly property:

const uiSchema = {
  fieldName: {
    "ui:readonly": true,
  },
};

This approach allows the field to be displayed without enabling editing.

3. Showing It and Allowing It to Be Edited

This is the default behavior for any field included in your JSON Schema without any specific uiSchema configurations that limit the interaction.

Implementing Conditional Logic

For more complex conditional logic (e.g., showing or hiding a field based on another field's value), you might need to dynamically adjust the schema or uiSchema based on the form's current state. RJSF provides a Form component that accepts onChange prop, which you can use to capture the form's state and then modify the schema or uiSchema accordingly.

Example:

Here's a basic example showing how you can adjust the uiSchema based on form data to make a field read-only or hidden:

import React, { useState } from 'react';
import Form from '@rjsf/core';

const MyForm = () => {
  const [formData, setFormData] = useState({});
  const [uiSchema, setUiSchema] = useState({});

  const schema = {
    type: 'object',
    properties: {
      showDetails: { type: 'boolean', title: 'Show details' },
      details: { type: 'string', title: 'Details' },
    },
  };

  const onChange = ({ formData }) => {
    setFormData(formData);
    setUiSchema({
      details: {
        "ui:widget": formData.showDetails ? "text" : "hidden",
        "ui:readonly": !formData.showDetails,
      },
    });
  };

  return (
    <Form schema={schema}
          formData={formData}
          onChange={onChange}
          uiSchema={uiSchema} />
  );
};

Alternative Packages

If react-jsonschema-form does not meet your needs for any reason, consider the following alternatives:

• JSONForms: This library offers extensive support for conditional rendering and dynamic schemas. It's built on top of JSON Schema and provides a higher level of abstraction, potentially simplifying complex form logic.
• formik-json-schema: While primarily a bridge between Formik and JSON Schema, with some custom development, you can leverage Formik's extensive capabilities for form management to implement complex visibility and editability logic.

Each package has its own set of trade-offs, including learning curve, community support, and flexibility. Choosing the right tool depends on your specific requirements, such as the complexity of your forms and the degree of customizability you need.

[thorwhalen]

A few screenshots of VsCode

A json mapping to forms

A text-based intellisense enabled json editor