> ## Documentation Index
> Fetch the complete documentation index at: https://mint-tsdocs.saulo.engineer/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenDocs Specification

> A universal documentation interchange format for multi-language code documentation

export const FileTree = ({structure, item, title, level = 0, maxDepth = 10, showIcons = true}) => {
  const getFileIcon = (fileName, hasChildren) => {
    if (hasChildren) {
      return 'folder-open';
    }
    return 'file';
  };
  if (structure !== undefined) {
    return <div data-component="tsdocs-filetree" className="code-block mt-5 mb-8 not-prose rounded-2xl relative group
                   text-gray-950 bg-gray-50 dark:bg-white/5 dark:text-gray-50
                   border border-gray-950/10 dark:border-white/10
                   p-0.5">
        {title && <div className="flex text-gray-400 text-xs rounded-t-[14px] leading-6 font-medium pl-4 pr-2.5 py-1">
            <div className="flex-none flex items-center gap-1.5 text-gray-700 dark:text-gray-300">
              {title}
            </div>
          </div>}
        <div className={`prose prose-sm dark:prose-invert w-0 min-w-full max-w-full py-3.5 px-4 bg-white dark:bg-codeblock overflow-x-auto scrollbar-thin scrollbar-thumb-rounded scrollbar-thumb-black/15 hover:scrollbar-thumb-black/20 dark:scrollbar-thumb-white/20 dark:hover:scrollbar-thumb-white/25 rounded-xt`} style={{
      fontFamily: 'ui-monospace, SFMono-Regular, monospace',
      fontSize: '0.875rem'
    }}>
          {structure.map((fileItem, index) => {
      if (!fileItem || !fileItem.name) return null;
      return <FileTree key={index} item={fileItem} level={0} maxDepth={maxDepth} showIcons={showIcons} />;
    })}
        </div>
      </div>;
  }
  if (!item) {
    return null;
  }
  if (level >= maxDepth) {
    return <div style={{
      paddingLeft: `${level * 20}px`,
      paddingTop: '4px',
      paddingBottom: '4px',
      color: '#6b7280',
      fontStyle: 'italic'
    }}>
        {showIcons && <Icon icon="AlertTriangle" />} (max depth reached)
      </div>;
  }
  const hasChildren = item.children != null && item.children.length > 0;
  const indent = level * 20;
  if (hasChildren) {
    return <div style={{
      position: 'relative',
      paddingLeft: `${indent}px`
    }}>
        {}
        {level > 0 && <div style={{
      position: 'absolute',
      left: `${indent - 12}px`,
      top: '20px',
      bottom: '0',
      width: '1px',
      backgroundColor: 'rgba(156, 163, 175, 0.2)',
      borderLeft: '1px solid rgba(156, 163, 175, 0.1)'
    }} />}
        <div style={{
      display: 'flex',
      alignItems: 'center',
      gap: '8px',
      paddingTop: '4px',
      paddingBottom: '4px'
    }}>
          {showIcons && <Icon icon={getFileIcon(item.name, true)} />}
          <span style={{
      fontWeight: 500
    }}>
            {item.name}
          </span>
          {item.description && <span style={{
      fontSize: '0.75rem',
      color: '#94a3b8',
      marginLeft: '8px'
    }}>
              {item.description}
            </span>}
          {item.badge && <Badge color={item.badge.color || 'blue'}>
              {item.badge.text}
            </Badge>}
        </div>
        {}
        {item.children && item.children.map((child, i) => {
      const key = child.name ? `${child.name}-${i}` : `child-${i}`;
      return <FileTree key={key} item={child} level={level + 1} maxDepth={maxDepth} showIcons={showIcons} />;
    })}
      </div>;
  }
  return <div style={{
    position: 'relative',
    paddingLeft: `${indent}px`,
    display: 'flex',
    alignItems: 'center',
    gap: '8px',
    paddingTop: '4px',
    paddingBottom: '4px'
  }}>
      {}
      {level > 0 && <div style={{
    position: 'absolute',
    left: `${indent - 12}px`,
    top: '0',
    bottom: '0',
    width: '1px',
    backgroundColor: 'rgba(156, 163, 175, 0.2)',
    borderLeft: '1px solid rgba(156, 163, 175, 0.1)'
  }} />}
      {showIcons && <Icon icon={getFileIcon(item.name, false)} />}
      <span>
        {item.name}
      </span>
      {item.description && <span style={{
    fontSize: '0.75rem',
    color: '#94a3b8',
    marginLeft: '8px'
  }}>
          {item.description}
        </span>}
      {item.badge && <Badge color={item.badge.color || 'blue'}>
          {item.badge.text}
        </Badge>}
    </div>;
};

<Note>
  **RFC Status**: This specification is currently a Request for Comments (RFC).

  Please provide feedback via [GitHub Issues](https://github.com/svallory/mintlify-tsdocs/issues)
  or start a discussion in our [Discussions](https://github.com/svallory/mintlify-tsdocs/discussions).
</Note>

## 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

| Version | Status    | Date    | Description                                  |
| ------- | --------- | ------- | -------------------------------------------- |
| 0.1.0   | RFC Draft | Current | Initial 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

<Note>
  **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.
</Note>

## Core Concepts

<CardGroup cols={2}>
  <Card title="Documentation Set" icon="library-big" href="/opendocs/opendocs-file-organization">
    A collection of OpenDocs JSON files representing your complete documentation
  </Card>

  <Card title="OpenDocs File" icon="file-json" href="/opendocs/opendocs-file-organization">
    The main opendocs.json file containing project organization and metadata
  </Card>

  <Card title="Project" icon="box" href="/opendocs/opendocs-file-organization">
    Individual documentable unit (crate, module, package, library)
  </Card>

  <Card title="DocItem" icon="shapes" href="/opendocs/opendocs-model">
    The fundamental unit of documentation - everything is a DocItem
  </Card>

  <Card title="DocBlock" icon="square-pilcrow" href="/opendocs/opendocs-model">
    Structured documentation content with description, tags, and metadata
  </Card>

  <Card title="Tags" icon="tag" href="/opendocs/opendocs-model">
    Documentation annotations (@param, @returns, @example, etc.)
  </Card>
</CardGroup>

### OpenDocs File Structure

<FileTree
  title="Documentation Set"
  structure={[
{
  name: "opendocs.json",
  description: "Entry point with DocumentationSet metadata",
  badge: { text: "Required", color: "blue" }
},
{
  name: "projects/",
  children: [
    {
      name: "auth-service.json",
      description: "Complete Project with items",
      badge: { text: "JSON", color: "green" }
    },
    {
      name: "web-sdk.json",
      description: "Complete Project with items",
      badge: { text: "JSON", color: "green" }
    },
    {
      name: "shared-types.json",
      description: "Complete Project with items",
      badge: { text: "JSON", color: "green" }
    }
  ]
}
]}
/>

### Key Relationships

<div className="not-prose mb-8">
  <div className="grid gap-3 text-sm">
    <div className="flex items-start gap-3 p-3 bg-white dark:bg-slate-800 rounded-lg border border-slate-200 dark:border-slate-700">
      <div className="w-2 h-2 bg-blue-500 rounded-full mt-2 flex-shrink-0" />

      <div>
        <span className="font-medium text-slate-900 dark:text-slate-100">Documentation Set</span>
         
        <span className="text-slate-600 dark:text-slate-400"> is a collection of OpenDocs JSON files</span>
      </div>
    </div>

    <div className="flex items-start gap-3 p-3 bg-white dark:bg-slate-800 rounded-lg border border-slate-200 dark:border-slate-700">
      <div className="w-2 h-2 bg-green-500 rounded-full mt-2 flex-shrink-0" />

      <div>
        <span className="font-medium text-slate-900 dark:text-slate-100">opendocs.json</span>
         
        <span className="text-slate-600 dark:text-slate-400"> is the main file containing project organization</span>
      </div>
    </div>

    <div className="flex items-start gap-3 p-3 bg-white dark:bg-slate-800 rounded-lg border border-slate-200 dark:border-slate-700">
      <div className="w-2 h-2 bg-purple-500 rounded-full mt-2 flex-shrink-0" />

      <div>
        <span className="font-medium text-slate-900 dark:text-slate-100">Project</span>
         
        <span className="text-slate-600 dark:text-slate-400"> contains multiple </span>
        <span className="font-medium text-slate-900 dark:text-slate-100">DocItems</span>
        <span className="text-slate-600 dark:text-slate-400"> (classes, functions, types, etc.)</span>
      </div>
    </div>

    <div className="flex items-start gap-3 p-3 bg-white dark:bg-slate-800 rounded-lg border border-slate-200 dark:border-slate-700">
      <div className="w-2 h-2 bg-teal-500 rounded-full mt-2 flex-shrink-0" />

      <div>
        <span className="font-medium text-slate-900 dark:text-slate-100">DocItem</span>
         
        <span className="text-slate-600 dark:text-slate-400"> contains exactly one </span>
        <span className="font-medium text-slate-900 dark:text-slate-100">DocBlock</span>
        <span className="text-slate-600 dark:text-slate-400"> (its documentation)</span>
      </div>
    </div>

    <div className="flex items-start gap-3 p-3 bg-white dark:bg-slate-800 rounded-lg border border-slate-200 dark:border-slate-700">
      <div className="w-2 h-2 bg-teal-500 rounded-full mt-2 flex-shrink-0" />

      <div>
        <span className="font-medium text-slate-900 dark:text-slate-100">DocItem</span>
         
        <span className="text-slate-600 dark:text-slate-400"> and can contain other </span>
        <span className="font-medium text-slate-900 dark:text-slate-100">DocItems</span>
        <span className="text-slate-600 dark:text-slate-400"> (hierarchical structure)</span>
      </div>
    </div>

    <div className="flex items-start gap-3 p-3 bg-white dark:bg-slate-800 rounded-lg border border-slate-200 dark:border-slate-700">
      <div className="w-2 h-2 bg-red-500 rounded-full mt-2 flex-shrink-0" />

      <div>
        <span className="font-medium text-slate-900 dark:text-slate-100">DocBlock</span>
         
        <span className="text-slate-600 dark:text-slate-400"> contains multiple </span>
        <span className="font-medium text-slate-900 dark:text-slate-100">Tags</span>
        <span className="text-slate-600 dark:text-slate-400"> (@param, @returns, @example, etc.)</span>
      </div>
    </div>
  </div>
</div>

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

<div className="not-prose">
  <JsonTree
    data={{
  "id": "my-library",
  "name": "My Library",
  "version": "1.0.0",
  "projects": [
    {
      "id": "main",
      "name": "Main Library",
      "language": "typescript",
      "version": "1.0.0",
      "items": [
        {
          "id": "main#Calculator",
          "name": "Calculator",
          "kind": "class",
          "language": "typescript",
          "docBlock": {
            "description": "A simple calculator class"
          }
        }
      ]
    }
  ]
}}
    title="Simple opendocs.json Example"
  />
</div>

## Getting Started

1. Read the [Design Principles](/opendocs/design-principles) to understand the philosophy behind OpenDocs
2. Review the [OpenDocs Model](/opendocs/opendocs-model) to understand Projects, DocItems, and DocBlocks
3. Learn about [File Organization](/opendocs/opendocs-file-organization) for structuring your Documentation Set

## Contributing

We welcome feedback and contributions:

* **Issues**: [Report problems or suggest improvements](https://github.com/svallory/mintlify-tsdocs/issues)
* **Discussions**: [Join the conversation](https://github.com/svallory/mintlify-tsdocs/discussions)
* **Pull Requests**: [Contribute to the specification](https://github.com/svallory/mintlify-tsdocs/pulls)

## License

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