JSON-DOC is a standardized format for storing structured content in JSON files, inspired by Notion's data model. It supports a wide variety of content types including paragraphs, headings, lists, tables, images, code blocks, and more.
This project provides:
- JSON Schema Specification: Complete schema definitions for all JSON-DOC structures
- Python Implementation: Full-featured Python library with validation and conversion tools
- TypeScript Implementation: TypeScript library with React renderer components
- Format Converters: Tools to convert between JSON-DOC and other formats (HTML, Markdown, etc.)
pip install python-jsondocnpm install @textcortex/jsondocfromjsondocimportload_json_doc, json_doc_dump_jsonfromjsondoc.convert.htmlimportconvert_html_to_json_doc# Load a JSON-DOC documentwithopen('document.json', 'r') asf:
doc=load_json_doc(f.read())
# Convert HTML to JSON-DOChtml_content="<h1>Hello World</h1><p>This is a paragraph.</p>"json_doc=convert_html_to_json_doc(html_content)
# Serialize back to JSONjson_str=json_doc_dump_json(json_doc)import{loadJsonDoc,JsonDocRenderer}from'@textcortex/jsondoc';importReactfrom'react';// Load and render a JSON-DOC documentconstApp=()=>{constdoc=loadJsonDoc(jsonDocData);return(<div><JsonDocRendererdocument={doc}/></div>);};- Structured Content: Documents represented as hierarchical blocks
- Rich Text Support: Text formatting with bold, italic, links, equations, and more
- Nested Blocks: Support for complex document structures with nested content
- Schema Validation: Full JSON Schema validation for all content types
- Text Blocks: Paragraphs, headings (1-3), quotes, code blocks
- List Blocks: Bulleted lists, numbered lists, to-do lists, toggles
- Media Blocks: Images (external URLs and file references), equations
- Layout Blocks: Columns, dividers, tables
- Interactive Blocks: To-do items with checkbox state
- Check schema/ for all block types
- Convert between JSON-DOC and all other formats with HTML as the intermediate format
.
├── schema/ # JSON Schema definitions
├── python/ # Python implementation
├── typescript/ # TypeScript implementation
├── docs/ # Documentation
├── examples/ # Example files and usage
└── .github/workflows/ # CI/CD pipelines
# Setupcd python
pip install -e ".[dev]"# Run tests
pytest
# Format code
ruff format .
ruff check .# Validate schemas
python tests/test_validation.py schema# Setupcd typescript
npm install
# Generate types from schemas
npm run generate-types
# Build
npm run build
# Run tests
npm test# Format code (runs automatically on commit)
npm run formatThe format is defined using JSON Schema with these core components:
- Page: Top-level container with metadata and children blocks
- Block: Content blocks of various types (paragraph, heading, list, etc.)
- Rich Text: Formatted text content with styling and annotations
- File: External file references for images and attachments
- Schema-First: All types generated programmatically from JSON schemas
- Validation: Comprehensive validation using JSON Schema
- Serialization: Perfect round-trip serialization between JSON and typed objects
- Extensibility: Easy to add new block types via schema updates
See the examples/ directory for:
- Sample JSON-DOC documents
- HTML conversion examples
- Usage patterns and best practices
- Fork the repository
- Create a feature branch
- Make your changes with tests
- Run the full test suite
- Submit a pull request
MIT License - see LICENSE for details.
Inspired by Notion's block-based document model. This project aims to provide an open, standardized format for structured content representation.