Skip to main content
RFC Status: This specification is currently a Request for Comments (RFC).Please provide feedback via GitHub Issues or start a discussion in our Discussions.

​
Overview

OpenDocs is a universal documentation interchange format designed to standardize how documentation is extracted, stored, and processed across different programming languages and documentation tools. It provides a language-agnostic way to represent API documentation that can be consumed by various documentation generators and platforms.

​
Specification Status

VersionStatusDateDescription
0.1.0RFC DraftCurrentInitial specification based on DocItem model

​
Key Principles

  • Language Agnostic: Works with any programming language
  • Template Friendly: Designed for consumption by template engines
  • Scalable: Handles projects from small libraries to massive monorepos
  • Extensible: Supports language-specific metadata without breaking compatibility
  • Standard Based: Uses established standards like JSON Schema and JSON $ref
Format Flexibility: The format: "json" property in OpenDocs files indicates the current format. This design allows for future support of additional formats, with JSONL (line-delimited JSON) being considered as the next format to support for streaming large documentation sets. The format property ensures forward compatibility as the specification evolves.

​
Core Concepts

Documentation Set

A collection of OpenDocs JSON files representing your complete documentation

OpenDocs File

The main opendocs.json file containing project organization and metadata

Project

Individual documentable unit (crate, module, package, library)

DocItem

The fundamental unit of documentation - everything is a DocItem

DocBlock

Structured documentation content with description, tags, and metadata

Tags

Documentation annotations (@param, @returns, @example, etc.)

​
OpenDocs File Structure

​
Key Relationships

Documentation Set   is a collection of OpenDocs JSON files
opendocs.json   is the main file containing project organization
Project   contains multiple DocItems (classes, functions, types, etc.)
DocItem   contains exactly one DocBlock (its documentation)
DocItem   and can contain other DocItems (hierarchical structure)
DocBlock   contains multiple Tags (@param, @returns, @example, etc.)

​
Why OpenDocs?

Traditional documentation tools are often tightly coupled to specific programming languages or frameworks. OpenDocs provides a common interchange format that allows:
  • Tool Interoperability: Extract documentation with one tool, render with another
  • Multi-Language Support: Document polyglot projects consistently
  • Performance: Efficient processing of large codebases through streaming formats
  • Flexibility: Language-specific extractors with universal consumers

​
Example OpenDocs File

Here’s a simple example of an opendocs.json file for a single-project Documentation Set:

​
Getting Started

  1. Read the Design Principles to understand the philosophy behind OpenDocs
  2. Review the OpenDocs Model to understand Projects, DocItems, and DocBlocks
  3. Learn about File Organization for structuring your Documentation Set

​
Contributing

We welcome feedback and contributions:

​
License

The OpenDocs Specification is licensed under the MIT License, making it free to implement and use in any project.