Skip to main content

JSON Schema

Overview​

To integrate your component API / JSON Schema into Storybook you can install an addon we've written specifically for that purpose:

Storybook JSON Schema Addon​

Displays associated JSON Schema documentation using a rich JSON Schema Explorer interface, and adds a validating JSON Code Editor with semantic auto-complete to interact with your components, and copy configurations with ease.

JSON Schema Explorer is based on the excellent Atlassian JSON Schema Viewer. It was slightly modified to generate bundles that can be imported for partial use, like this addon does.

JSON Code Editor is based on @monaco-editor/react. The editor is connected to your story state / args, so changing props through Controls is reflected in the code shown. Vice-versa if you edit the JSON, and the result is valid according to the schema, your changed args are applied to the story, too.

Show me a working demo (click on the JSON Schema addon tab)

View the addon on Github: https://github.com/kickstartDS/storybook-addon-jsonschema
Or directly on Storybooks page: https://storybook.js.org/addons/@kickstartds/storybook-addon-jsonschema

Image showing the JSON Schema addon in action

What it's for​

Three things you can use this addon for:

  1. Explore associated JSON Schema documentation, in a nicely organized fashion in the JSON Schema Explorer
  2. Configure components through Controls, copy the resulting JSON as a starting point or template for API-usage / data generation purposes in the JSON Code Editor
  3. Paste JSON to validate data or preview component state in the JSON Code Editor

Getting started​

Prerequesite: Your components need to have JSON Schema files associated with them. Additionally schemas need to be dereferenced already, as $ref-resolution is not (a tested) part of this addon (yet? ... let us know in the issues if you need this).

First step is to install the addon:


_10
$ yarn add --dev @kickstartds/storybook-addon-jsonschema

Second step, register the addon inside your .storybook/main.js (just add it to the list):


_10
module.exports = {
_10
addons: ['@kickstartds/storybook-addon-jsonschema'],
_10
};

Third step, export the schema as component- or story parameter:


_20
export default {
_20
title: 'Button',
_20
component: Button,
_20
parameters: {
_20
jsonschema: {
_20
$schema: 'http://json-schema.org/draft-07/schema#',
_20
$id: 'https://my-components/button.schema.json',
_20
type: 'object',
_20
properties: {
_20
primary: {
_20
type: 'boolean',
_20
default: false,
_20
},
_20
label: {
_20
type: 'string',
_20
},
_20
},
_20
},
_20
},
_20
};

For a detailed explanation on how to add this to your project, have a look at part three of our "Create your Design System" guide.

Advanced configuration​

This addon is still early, advanced configuration options will be added at a later date. Feel free to let us know in the issues if something specific is unclear, or doesn't work!