Overview

TDL uses an extensible core architecture: a lightweight, portable core spec with optional extensions that add capabilities without breaking compatibility.

Core Principles

1. Graceful Degradation: Files using extensions MUST parse in any TDL renderer

2. Additive Only: Extensions enhance but never break core functionality

3. Independent Versioning: Extensions evolve separately from core spec

4. Warn on Undeclared Use: Using extension features without declaring them triggers warnings

Official Extensions

Extension	Version	Status	Description
icons	1.0	Stable	Icon support for nodes
code	1.0	Stable	Code block attachments
links	1.0	Draft	Clickable URLs on nodes
tooltips	1.0	Draft	Hover tooltips with descriptions

See the full Extension Roadmap for planned and proposed extensions.

Using Extensions

Declaring Extensions

Add a pragma at the top of your TDL file:

#!ext icons,code
@arch My Diagram
[nodes]
  db:Database|icon:postgresql

Versioned Extensions

Specify versions for reproducibility:

#!ext [email protected],[email protected]

What Happens Without Declaration?

If you use extension features without declaring them:

• Parser: Parses successfully (graceful degradation)

• Semantic Analyzer: Emits a warning (W103 for icons, W104 for code)

• Renderer: May or may not render the feature

Example warning:

WARNING W103: Using icon 'postgresql' without declaring ext:icons.
Add '#!ext icons' at the top of your file

How Extensions Work

Core Features (Always Work)

• Nodes, edges, groups, flows

• Shapes (rect, cyl, diamond, etc.)

• Tags and colors

• Nested diagrams

Extension Features (Require Declaration)

Feature	Extension	ASCII Renderer	SVG Renderer
|icon:name	ext:icons	Ignored	Shows icon
[code] section	ext:code	Ignored	Shows code panel
|code:blockId	ext:code	Ignored	Links to code

For Extension Authors

See the Extension Authoring Guide for:

• How to design an extension

• Syntax guidelines

• Graceful degradation requirements

• Publishing process

Extension Lifecycle

Draft → Stable → Deprecated → Removed
  │        │          │
  │        │          └── Still parses, warning emitted
  │        └── Fully supported, versioned
  └── Experimental, API may change

Future Extensions (Planned)

Extension	Description	Status
ext:status	Lifecycle status indicators	Proposed
ext:annotations	Callouts and legends	Proposed
ext:live	Real-time data integration	Idea
ext:a11y	Accessibility metadata	Idea
ext:ownership	Team ownership metadata	Idea
ext:metrics	Performance/capacity data	Idea

See the Roadmap for detailed specifications of each proposed extension.

FAQ

Q: Do I need to declare extensions for existing TDL files? A: Existing files will continue to work, but you'll see warnings. Add the pragma to silence them and make your intent explicit.

Q: Can I create my own extension? A: Yes! See the Authoring Guide. Community extensions use namespaced identifiers like community:my-ext.

Q: What if a renderer doesn't support an extension? A: The file still parses and renders - extension-specific features are gracefully ignored.