README.md

React JSON Schema Inspector

Introducing a component for viewing/traversing (complex) JSON Schemas for the sake of documentation and potentially assisting users of a domain-specific model in finding a particular piece of information.

The component is expressly not intended for visualising the whole of a JSON Schema (there are already quite a few JSON Schema Viewer components out there doing a great job at that). A possible use-case is inside an application that allows its users to define business rules or other kinds of expressions (e.g. within decision tables) while providing rather complex data structures as input which may also be subject to frequent changes – both good reasons why you wouldn't want to maintain a separate documentation of the all of the available fields. And the majority of generated forms of documentation (e.g. JSDoc, JavaDoc, etc.) may be too big/technical for your users.

At the same time, there are a number of tools that automatically generate schema definitions from your code. Taking these automatically generated schemas, the JSON Schema Inspector component allows your users to iterate through the data structure (if they know roughly where to look) or even search through the whole structure to find the particular piece of information they are looking for. All the while showing the path to the selected field as breadcrumbs underneath, allowing your users to simply copy-paste it into their business rule/expression.

Demo

Have a look at the Storybook

Or try it out and

Usage

Installation from NPM

npm i react-jsonschema-inspector

React Component Props of <Inspector>

Prop	Description
schemas (required)	Object: keys will be displayed in the root column, the values are expected to be independent JSON Schema definitions (compatible to Draft 6, 7 or 2019-09)
referenceSchemas	Array of objects: the entries are expected to be JSON Schema definitions with an absolute URI as $id (compatible to Draft 6, 7 or 2019-09). These schemas will not be shown on the root column, but are used to resolve URI $ref-erences in any of the displayed schemas or in another entry of the referenceSchemas
hideSingleRootItem	Boolean: flag indicating whether the properties of the single entry in the given schemas properties should be listed in the root column – in case of multiple entries in schemas this is being ignored
defaultSelectedItems	Array of strings: each referring to the name of the selected item in the respective column (i.e. the first entry in this array should match one key in the schemas object)
onSelect	Function: call-back being invoked after the selection changed. Receives two parameters: (1) the selection - as per the defaultSelectedItems, (2) an object containing the "columnData" - the full render information for all visible columns
buildArrayProperties	Function: accepting a JsonSchema instance representing an array's declared type of items and returning an object listing the available properties to offer with either JsonSchema or raw JSON Schemas as values. The default, providing access to the array's items, is: arrayItemSchema => ({ "[0]": arrayItemSchema })
parserConfig	Object: enabling the inclusion/exclusion of optional parts of a JSON Schema – both for the inclusion of properties and their attributes as well as in the search.
parserConfig.anyOf	Object: specifying details of the inclusion of JSON Schema parts wrapped in anyOf.
parserConfig.anyOf.groupTitle	String: alternative title to show in option selection column – defaults to "any of"
parserConfig.anyOf.optionNameForIndex	Function: providing the name/label to show for a single option – defaults to (optionIndexes) => `Option ${optionIndexes.map(index => index + 1).join("-")}` , resulting in e.g. "Option 1", "Option 2-1", "Option 3"
parserConfig.oneOf	Object: specifying details of the inclusion of JSON Schema parts wrapped in oneOf.
parserConfig.oneOf.groupTitle	String: alternative title to show in option selection column – defaults to "one of"
parserConfig.oneOf.optionNameForIndex	Function: providing the name/label to show for a single option – defaults to (optionIndexes) => `Option ${optionIndexes.map(index => index + 1).join("-")}` , resulting in e.g. "Option 1", "Option 2-1", "Option 3"
breadcrumbs	Object: enabling the definition of options for the breadcrumbs feature in the footer (can be disabled by setting to null)
breadcrumbs.prefix	String: to be shown in front of the root selection (e.g. "//" or "./") – defaults to ""
breadcrumbs.separator	String: to be shown in front of any non-root selection (e.g. "/") – defaults to "."
breadcrumbs.skipSeparator	Function: expecting a JsonSchema as input and should return an object containing JsonSchema or raw JSON Schemas as values – defaults to excluding "[0]"
breadcrumbs.mutateName	Function: expecting the following inputs: (1) the selected item's name, (2) the full information for the respective column and (3) the index of the respective column; a column's breadcrumb can be skipped by returning null
breadcrumbs.preventNavigation	Boolean: set to true in order to turn-off the default behaviour of discarding any following selections when double-clicking on a breadcrumbs item
searchOptions	Object: enabling the definition of options for the search/filter feature in the header (is disabled by default) – either searchOptions.fields or searchOptions.filterBy needs to be specified to enable it. the component itself will take care of looking-up sub-schemas (e.g. in properties) and also respects $ref-erences and has no problem with circular references.
searchOptions.fields	Array of strings: each referring to the name of a text field in a JSON Schema (e.g. ["title", "description"]) in which to search/filter – this applies a case-insensitive contains() check on each of the given fields
searchOptions.filterBy	Function: overrides the default search logic based on searchOptions.fields. Input is a raw JSON Schema (i.e. as plain object), output is expected to be a boolean indicating whether an immediate match was found
searchOptions.byPropertyName	Boolean: toggle to enable/disable additional filter option besides fields/filterBy, checking for case-insensitive (partial) matches on property names.
searchOptions.inputPlaceholder	String: for setting the input hint in the search field. This defaults to "Search".
searchOptions.debounceWait	Number indicating the delay in milliseconds between the last change to the search term being entered and it actually being applied. This defaults to 200 but may be increased when used with exceptionally large schemas and you experience performance issues. Please refer to the documentation on lodash.debounce.
searchOptions.debounceMaxWait	Number indicating the maximum delay in milliseconds after the search term was changed. This defaults to 500. Please refer to the documentation on lodash.debounce.
renderHeaderToolBar	Function: custom render function for additional header tool-bar besides search input. Receives one parameter: object with a: "columnData" property
renderSearchInput	Function: custom render function for the search input. Receives one parameter: object with the following properties: "searchFilter", "placeholder", "onChange"
renderItemContent	Function: custom render function for name of single property/sub-schema in a column. Receives one parameter: object with the following properties: "name", "hasNestedItems", "selected", "schemaGroup"
renderSelectionDetails	Function: custom render function for the "Details" block on the right for the single property/sub-schema being selected. Receives one parameter: object with the following properties: "itemSchemaGroup", "columnData", "selectionColumnIndex", "optionIndexes"
renderEmptyDetails	Function: custom render function for the "Details" block on the right if nothing is selected yet. Receives one parameter, which is an object with the "rootColumnSchemas" property, which holds the array of top-level schemas (as derived from the schemas prop and augmented by any given referenceSchemas)

Additional Helper Functions

Besides the main <Inspector> component, there are additional named helper functions being provided in the scope of this library:

• getFieldValueArrayFromSchemaGroup() – listing all values of the targeted field in an array (skipping undefined and null values)
• getCommonFieldValuesFromSchemaGroup() – listing only those values of the targeted field in an array that are included in all occurrences of the field not being undefined or null
• getMinimumFieldValueFromSchemaGroup() – expecting numeric values in the targeted field and returning the single lowest value (ignoring undefined and null values)
• getMaximumFieldValueFromSchemaGroup() – expecting numeric values in the targeted field and returning the single highest value (ignoring undefined and null values)

All four of these are intended to be used within props enabling the customisation of an <Inspector> instance, e.g. in onSelect, buildArrayProperties, breadcrumbs.mutateName, renderItemContent, renderSelectionDetails, renderEmptyDetails. All four helper functions expect the same input parameters:

1. schemaGroup – a group object representing a single schema with all its parts, as provided to the various call-back functions mentioned above
2. fieldName – textual name of the targeted field in the schema (group), e.g. "title", "maximum", "minLength"
3. defaultValue – value to return if there is no value for the targeted field; or as initial/base value for the Array.reduce() being performed for the encountered values
4. optionIndexes – only provided if the schemaGroup contains optional parts (i.e. anyOf/oneOf); used to identify the particular optional path within the anyOf/oneOf part(s) – this is also provided in one way or another in those call-back functions listed above

As output, the respective helper functions either return a single value or – in case of multiple values – an array.

Compatibility

This component supports JSON Schema Draft 2019-09. It is also backwards-compatible with Drafts 4, 6 and 7.

Please refer to the more detailed listing below regarding particular keywords.

Structural Properties

Property	Support	Description
$schema	-	ignored (assumed to be compatible to JSON Schema Draft 6, 7 or 2019-09)
$vocabulary	-	ignored
$id	Yes	allowed as sub-schema reference in $ref or as source for the base URI to prepend to a non-fragment $ref (as per Draft 6 upwards), but not displayed; ignored if specified anywhere but in the root schema or inside an entry in $defs/definitions
id	-	ignored (as of release 5.0.0)
$anchor	Yes	allowed as sub-schema reference in $ref (as per Draft 2019-09) when preceded by #, but not displayed; ignored if specified anywhere but in the root schema or inside an entry in $defs/definitions
$ref	Yes	used to look-up re-usable sub-schemas transparently (i.e. not displayed), supporting: # or the root $id/id value as root schema references, #/$defs/<name-of-definition>/#/definitions/<name-of-definition> or the respective $id/id value from within the $defs/definitions for sub-schemas, absolute URIs are supported as long as those separate schemas are provided via the referenceSchemas prop (and their respective root $id/id matches the given $ref) absolute URIs ending with #/$defs/<name-of-definition>/#/definitions/<name-of-definition> or #<anchor> are also supported via the referenceSchemas prop
$recursiveAnchor	-	ignored
$recursiveRef	Partially	treated as alias for $ref but not yet for advanced scenarios involving $recursiveAnchor (as per Draft 2019-09)
$defs	Yes	used to provide re-usable sub-schemas that are being referenced via $ref (only in the respective root schemas) (as per Draft 2019-09)
definitions	Yes	used to provide re-usable sub-schemas that are being referenced via $ref (only in the respective root schemas) (as per Draft 6 or 7)
properties	Yes	used to populate the whole structure to be traversed
required	Yes	used to add empty properties to structure if they are not also mentioned in properties directly
additionalProperties	-	ignored
patternProperties	-	ignored
propertyNames	-	ignored
unevaluatedProperties	-	ignored
items	Partially	used to look-up properties of single kind of items in an array; however if items is an array of multiple sub-schemas they are being ignored
additionalItems	Yes	used to look-up properties of kind of items in an array if items is not present or defined as an array (which is not supported itself), otherwise additionalItems are being ignored
unevaluatedItems	-	ignored
allOf	Yes	used to combine sub-schemas transparently
anyOf	Yes	used to combine sub-schemas
oneOf	Yes	used to combine sub-schemas
not	-	ignored
contains	-	ignored
dependencies	-	ignored
dependentSchemas	-	ignored
if	-	ignored
then	-	ignored
else	-	ignored

Non-Structural Properties (shown in default "Details" form)

Property	Support	Comment
title	Yes
description	Yes
examples	Yes	without further formatting
default	Yes	without further formatting
type	Yes
enum	Yes	without further formatting
const	Yes	without further formatting
minLength	Yes
maxLength	Yes
pattern	Yes
format	Yes	without further explanations
multipleOf	Yes
minimum	Yes
exclusiveMinimum	Yes	supported both as number per Draft 6 upwards and boolean per Draft 4
maximum	Yes
exclusiveMaximum	Yes	supported both as number per Draft 6 upwards and boolean per Draft 4
required	Yes	not on the individual items per default
dependentRequired	-	ignored
minItems	Yes
maxItems	Yes
uniqueItems	Yes
minContains	-	ignored
maxContains	-	ignored
minProperties	-	ignored
maxProperties	-	ignored