Interactive JSON Schema documentation generator with example-first approach
npm install json-schema-explorerAn interactive, example-first tool to generate beautiful reference documentation from JSON Schema files. Perfect for documenting configuration files for your projects. Built with TypeScript and bundled with Rollup.js.
- š Example-First Approach - Displays your configuration example prominently
- šÆ Interactive Hover - Hover over any property to see its documentation in real-time
- š Multi-Format Support - Toggle between JSON, YAML, and TOML formats instantly
- šØ Syntax Highlighting - Color-coded tokens for better readability
- š Comprehensive Display - Shows all schema metadata including:
- Property titles and descriptions
- Types, formats, and constraints (min/max, patterns, etc.)
- Default values and examples
- Allowed values (enums)
- References to definitions
- š» TypeScript - Fully typed with TypeScript for better IDE support and type safety
- šØ Clean UI - Professional two-column layout with side-by-side example and documentation
- šØ Customizable Styling - CSS custom properties for easy theming
- š± Responsive Design - Works on all screen sizes
- š§ Rollup.js - Efficient bundling with source maps for debugging
- āæ Accessible - WCAG AA compliant with full keyboard navigation
1. Load your JSON Schema - Either upload a file or use the example
2. See your example - The tool displays the first example from your schema (or generates one)
3. Hover to learn - Hover over any property in the example to see its full documentation
This approach makes it easy for users to understand your configuration by seeing a real example first, then exploring the details of each property interactively.
If you're building a tool that uses JSON or YAML configuration files, you can create a JSON Schema for that configuration and use this tool to generate beautiful, user-friendly reference documentation for your users.
The example-first approach is inspired by tools like composer.json.jolicode.com and provides a more intuitive way to explore configuration options compared to traditional reference documentation.
1. Clone this repository
2. Install dependencies:
``bash`
yarn install
`
3. Build the TypeScript code:
bash`
yarn run build
`
4. Serve the files with any HTTP server:
bash`
yarn run serve
http://localhost:8000/demo/
5. Open in your browser
6. Click "Load Example" to see the sample documentation
7. Or upload your own JSON Schema file
For development with automatic rebuilding:
`bash`
yarn run watch
This watches for changes in the TypeScript source and automatically rebuilds.
Simply click the file input button and select your JSON Schema file (.json). The documentation will be generated automatically from the first example in your schema, or one will be generated from the schema properties.
You can also use the SchemaExplorer class programmatically with custom element selectors or direct element references:
`javascript
// Load your schema
const schema = await fetch('your-schema.json').then(r => r.json());
// Option 1: Using CSS selectors
const explorer = new SchemaExplorer(schema, {
schemaPanel: '#panel-schema', // Any CSS selector
documentationPanel: '#panel-documentation' // ID, class, or any selector
});
// Option 2: Using HTML element references
const schemaPanelEl = document.getElementById('panel-schema');
const docPanelEl = document.getElementById('panel-documentation');
const explorer2 = new SchemaExplorer(schema, {
schemaPanel: schemaPanelEl, // Direct HTMLElement reference
documentationPanel: docPanelEl // Direct HTMLElement reference
});
// Option 3: Mix both approaches
const explorer3 = new SchemaExplorer(schema, {
schemaPanel: '#panel-schema', // CSS selector
documentationPanel: document.querySelector('.doc-panel') // HTMLElement
});
`
Parameters:
- schema (required): The JSON Schema objectoptions
- (optional): Configuration object with:schemaPanel
- : CSS selector string or HTMLElement for the schema panel (default: '#panel-schema')documentationPanel
- : CSS selector string or HTMLElement for the documentation panel (default: '#panel-documentation')placeholderText
- : String to display in the documentation panel before hovering over a property (default: 'Hover over a property in the example to see its documentation.')formats
- : Array of format types to display as toggle buttons (default: ['json', 'yaml', 'toml']). The buttons will be displayed in the order specified.
Examples with custom formats:
`javascript
// Display only YAML and JSON formats (in that order)
new SchemaExplorer(schema, {
schemaPanel: '#panel-schema',
documentationPanel: '#panel-documentation',
formats: ['yaml', 'json']
});
// Display only TOML format
new SchemaExplorer(schema, {
schemaPanel: '#panel-schema',
documentationPanel: '#panel-documentation',
formats: ['toml']
});
// Default behavior (all three formats)
new SchemaExplorer(schema, {
schemaPanel: '#panel-schema',
documentationPanel: '#panel-documentation'
});
`
Features:
- Format Switching: Click JSON, YAML, or TOML buttons to switch formats
- Interactive Elements: Hover over any property to see its documentation
- Syntax Highlighting: Color-coded tokens for keys, values, strings, numbers, booleans
Event Handling:
You can listen to events emitted by the SchemaExplorer instance:
`javascript
const explorer = new SchemaExplorer(schema, {
schemaPanel: '#panel-schema',
documentationPanel: '#panel-documentation'
});
// Listen to property clicks
explorer.on('propertyClick', (instance, event) => {
const path = instance.getPropertyPath();
console.log('Property clicked:', path ? path.join('.') : 'none');
});
// Programmatically select a property
explorer.setPropertyPath(['instance', 'max_logs_buffer_size']);
`
Available Events:
- propertyClick: Emitted when a user clicks on a property in the schema.
Public Methods:
- on(eventType, handler): Register an event handler. Returns the SchemaExplorer instance for method chaining.getPropertyPath()
- : Returns the currently displayed property path as an array of strings/numbers, or null if no property is displayed.setPropertyPath(path)
- : Programmatically selects a property by its path (e.g., ['instance', 'max_logs_buffer_size']). Shows the property documentation, highlights the token, and emits a propertyClick event. Returns the SchemaExplorer instance for method chaining.
Edit demo/example-schema.json to change the example schema that loads when you click "Load Example".
``
.
āāā demo/
ā āāā index.html # Interactive demo page
ā āāā example-schema.json # Sample schema file
ā āāā README.md # Demo documentation
āāā src/
ā āāā schema-explorer.ts # TypeScript source code (fully documented with JSDoc)
ā āāā schema-explorer.css # Library CSS styling (with CSS custom properties)
āāā dist/ # Built files (generated)
ā āāā schema-explorer.js # IIFE bundle for browsers
ā āāā schema-explorer.esm.js # ES module bundle
ā āāā schema-explorer.cjs.js # CommonJS bundle
ā āāā schema-explorer.umd.js # UMD bundle
ā āāā schema-explorer.css # Bundled CSS with comprehensive documentation
ā āāā schema-explorer.d.ts # TypeScript declarations
ā āāā *.map # Source maps
āāā package.json # NPM package configuration
āāā tsconfig.json # TypeScript configuration
āāā rollup.config.js # Rollup bundler configuration (with CSS watch support)
āāā README.md # This file
āāā USAGE.md # Detailed usage guide
The project uses TypeScript and Rollup.js for the build process:
1. TypeScript Compilation: Source code in src/ is compiled with type checkingdist/schema-explorer.js
2. Rollup Bundling: Creates two output formats:
- - IIFE format for direct browser usedist/schema-explorer.esm.js
- - ES module format for bundlersdist/schema-explorer.cjs.js
- - CommonJS bundle for Node.jsdist/schema-explorer.umd.js
- - UMD bundle for CDN usage.d.ts
3. Type Definitions: Generates files for TypeScript consumers
4. Source Maps: Includes source maps for debugging
Build Commands:
- yarn run build - Build onceyarn run watch
- - Watch mode for developmentyarn run serve
- - Start local server
This tool fully supports JSON Schema Draft 7 and 2020-12, including all keywords from the specification:
, number, integer, boolean, array, object
- enum - Enumerated values
- const - Constant value (2020-12)$3
- minimum / maximum - Inclusive bounds
- exclusiveMinimum / exclusiveMaximum - Exclusive bounds (2020-12)
- multipleOf - Multiple constraint$3
- minLength / maxLength - Length constraints
- pattern - Regular expression pattern
- format - Format validation (date, email, uuid, etc.)
- contentMediaType / contentEncoding - Content metadata (2020-12)$3
- items - Item schema validation
- prefixItems - Tuple validation (2020-12, replaces old tuple syntax)
- minItems / maxItems - Size constraints
- uniqueItems - Uniqueness constraint
- contains / minContains / maxContains - Contains validation (2020-12)$3
- properties - Property schemas
- patternProperties - Pattern-based property matching
- additionalProperties - Additional properties validation
- propertyNames - Property name validation
- required - Required properties
- minProperties / maxProperties - Size constraints
- dependentRequired / dependentSchemas - Dependencies (2020-12)$3
- allOf - Must match all schemas
- anyOf - Must match any schema
- oneOf - Must match exactly one schema
- not - Must not match schema$3
- if / then / else - Conditional validation (Draft 7+)$3
- title / description - Documentation
- default - Default value
- examples - Example values
- deprecated - Deprecation marker (2020-12)
- readOnly / writeOnly - Property hints (2020-12)
- $comment - Schema comments (2020-12)$3
- $ref - Schema references
- $defs / definitions - Schema definitionsTechnology Stack
- TypeScript - Type-safe development with interfaces, strict typing, and comprehensive JSDoc comments
- Rollup.js - Fast bundler with tree-shaking, ES module support, and CSS watch mode
- HTML5 - Structure
- CSS3 - Modern styling with CSS custom properties for easy theming
- marked - Markdown parser (bundled dependency)
- js-yaml - YAML format support (bundled dependency)
- smol-toml - TOML format support (bundled dependency)
- Minimal runtime - Compiles to optimized JavaScript with only essential dependencies
Browser Compatibility
Works in all modern browsers (Chrome, Firefox, Safari, Edge) that support ES6+ JavaScript.
Publishing to NPM
This package is automatically published to NPM when a new release is created on GitHub.
$3
1. Create a Release: Go to the Releases page and create a new release with a version tag (e.g.,
v1.0.0)
2. GitHub Actions: The release triggers a GitHub Actions workflow that:
- Installs dependencies
- Builds the package
- Publishes to NPM with provenance
3. NPM Package: The package becomes available at npmjs.com/package/json-schema-explorer$3
For the automated publishing to work, a repository admin needs to:
1. Create an NPM access token with publish permissions at npmjs.com/settings/tokens
2. Add the token as a repository secret named
NPM_TOKEN in GitHub Settings > Secrets and variables > Actions$3
To manually publish the package (not recommended, use GitHub releases instead):
`bash
yarn run build
yarn publish --access public
``This project is open source and available under the MIT License.
Contributions are welcome! This is meant to be simple and maintainable, so please keep changes minimal and well-documented.