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

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:devicon-postgresql

Rendered diagram

What Happens Without Declaration?

If you use extension features without declaring them:

• Parser: Parses successfully (graceful degradation)

• Semantic Analyzer: Emits a warning

• Renderer: will 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

A detailed guide will be coming soon on how to build your own extension, which will include

• How to design an extension

• Syntax guidelines

• Graceful degradation requirements

• Publishing process

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

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! Details will be published with the release of V1 Spec of TDL Core.

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