JSON Schema Explorer

An 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.

Features

• 📄 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

How It Works

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.

Use Case

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.

Getting Started

Development Setup

1. Clone this repository
2. Install dependencies:

   yarn install

3. Build the TypeScript code:

   yarn run build

4. Serve the files with any HTTP server:

   yarn run serve

5. Open http://localhost:8000/demo/ in your browser
6. Click "Load Example" to see the sample documentation
7. Or upload your own JSON Schema file

Development Mode

For development with automatic rebuilding:

yarn run watch

This watches for changes in the TypeScript source and automatically rebuilds.

Using Your Own Schema

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.

Programmatic Usage

You can also use the SchemaExplorer class programmatically with custom element selectors or direct element references:

// 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 object
• options (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:

// 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:

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.

Customizing the Example

Edit demo/example-schema.json to change the example schema that loads when you click "Load Example".

File Structure

.
├── 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

Build Process

The project uses TypeScript and Rollup.js for the build process:

1. TypeScript Compilation: Source code in src/ is compiled with type checking
2. Rollup Bundling: Creates two output formats:

• dist/schema-explorer.js - IIFE format for direct browser use
• dist/schema-explorer.esm.js - ES module format for bundlers
• dist/schema-explorer.cjs.js - CommonJS bundle for Node.js
• dist/schema-explorer.umd.js - UMD bundle for CDN usage

3. Type Definitions: Generates .d.ts files for TypeScript consumers
4. Source Maps: Includes source maps for debugging

Build Commands:

• yarn run build - Build once
• yarn run watch - Watch mode for development
• yarn run serve - Start local server

JSON Schema Support

This tool fully supports JSON Schema Draft 7 and 2020-12, including all keywords from the specification:

Type Validation

• Basic types: string, number, integer, boolean, array, object
• enum - Enumerated values
• const - Constant value (2020-12)

Numeric Validation

• minimum / maximum - Inclusive bounds
• exclusiveMinimum / exclusiveMaximum - Exclusive bounds (2020-12)
• multipleOf - Multiple constraint

String Validation

• minLength / maxLength - Length constraints
• pattern - Regular expression pattern
• format - Format validation (date, email, uuid, etc.)
• contentMediaType / contentEncoding - Content metadata (2020-12)

Array Validation

• 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)

Object Validation

• 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)

Schema Composition

• allOf - Must match all schemas
• anyOf - Must match any schema
• oneOf - Must match exactly one schema
• not - Must not match schema

Conditional Schemas

• if / then / else - Conditional validation (Draft 7+)

Metadata & Annotations

• 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)

References

• $ref - Schema references
• $defs / definitions - Schema definitions

Technology 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.

Automated Publishing Process

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

Setup Requirements

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

Manual Publishing

To manually publish the package (not recommended, use GitHub releases instead):

yarn run build
yarn publish --access public

License

This project is open source and available under the MIT License.

Contributing

Contributions are welcome! This is meant to be simple and maintainable, so please keep changes minimal and well-documented.