Specification (v0.1)

This is the formal language specification. For practical usage, see the Getting Started guide.

1. Introduction

TDL (TOON Diagram Language) is a minimal, token-efficient language for describing software architecture and other technical diagrams.

1.1 Design Principles

1. Minimal Quoting - Simple strings need no quotes

2. Semantic Indentation - Structure through whitespace

3. Token Efficiency - Optimized for AI generation

4. Auto-Layout - Focus on relationships, not positioning

5. Graceful Degradation - Extensions don't break parsers

1.2 Version

This document specifies TDL version 0.1 (pre-release).

2. Document Structure

2.1 Diagram Type Declaration

Every TDL document begins with a type declaration:

@type

Valid types:

• @arch - Architecture diagrams

• @seq - Sequence diagrams

• @flow - Flowcharts

• @state - State machines (draft)

• @er - Entity-relationship (draft)

2.2 Extension Pragma

Optional extension declarations follow the type:

@arch
#!ext icons,code

2.3 Sections

Content is organized into sections:

[section-name]
  content

Core sections:

• [nodes] - Component definitions

• [edges] - Connections

• [groups] - Logical groupings

• [styles] - Named edge styles

• [tags] - Tag definitions

• [flow:name] - Animation flows

• [nested:id] - Nested diagrams

3. Nodes

3.1 Basic Syntax

id:Label

• id - Alphanumeric identifier (a-z, A-Z, 0-9, _)

• Label - Display text

3.2 Properties

id:Label|property:value|property:value

Node properties:

Property	Values	Example
shape	See §3.3	|cyl
color	Named or hex	|color:red
icon	Icon name	|icon:aws-lambda
group	Group name	|group:Backend
tags	Comma-separated	|tags:prod,aws
expandable	Flag	|expandable

3.3 Shapes

Shape	Syntax	Description
Rectangle	|rect	Default
Cylinder	|cyl	Database/storage
Cloud	|cloud	External/cloud
Diamond	|diamond	Decision/routing
Oval	|oval	Actor/process
Hexagon	|hex	Adapter/port
Document	|doc	File/config
Group	|grp	Boundary
Terminator	|terminator	Start/end
Data	|data	I/O
Subprocess	|subproc	External process
Manual	|manual	Human action

4. Edges

4.1 Operators

Operator	Style	Direction
->	Solid	Forward
-->	Dashed	Forward
..	Dotted	None
<->	Solid	Both
<-->	Dashed	Both

4.2 Labels

source->target:label

4.3 Styling

source->target|color:red|width:2|dash:5,5
source->target|style:stylename

5. Groups

5.1 Block Syntax

[nodes]
  [Group Name]
    node1:Node 1
    node2:Node 2

5.2 Compact Syntax

[nodes]
  node1:Node 1|group:Backend
  node2:Node 2|group:Backend

5.3 Nested Groups

[nodes]
  [Outer]
    [Inner]
      node:Node

6. Styles

6.1 Definition

[styles]
  name: property:value|property:value

6.2 Usage

[edges]
  a->b|style:name

6.3 Override

[edges]
  a->b|style:name|color:red

7. Flows

7.1 Definition

[flow:name]
  intro:Introduction text
  1:source->target:Step description
  2:source->target:Step description
  outro:Conclusion text

7.2 Multiple Flows

Multiple [flow:name] sections allowed per document.

8. Extensions

8.1 Declaration

#!ext extension1,extension2

8.2 Official Extensions

Extension	Version	Status
icons	1.0	Stable
code	1.0	Stable
links	1.0	Draft
tooltips	1.0	Draft

8.3 Graceful Degradation

Unknown extensions and properties are ignored with warnings.

9. Lexical Rules

9.1 Whitespace

• Indentation: 2 spaces recommended

• Blank lines allowed between sections

9.2 Comments

# This is a comment
node:Node  # Inline comment

9.3 Strings

Simple strings need no quotes:

node:My Service Name

Quoted strings for special characters:

node:"GET /api/users/{id}"

9.4 Identifiers

Valid: a-z, A-Z, 0-9, _ Must start with letter or underscore.

10. Error Handling

10.1 Error Codes

Code	Description
E001	Invalid diagram type
E002	Unknown node reference
E003	Duplicate node ID
E004	Invalid property
E005	Syntax error

10.2 Warning Codes

Code	Description
W101	Unknown property (ignored)
W102	Unknown shape (using default)
W103	Undeclared extension usage
W104	Unknown icon

11. EBNF Grammar

document      = type-decl, [extension-pragma], {section} ;
type-decl     = "@", type-name, newline ;
type-name     = "arch" | "seq" | "flow" | "state" | "er" ;
extension-pragma = "#!ext", extension-list, newline ;
extension-list = identifier, {",", identifier} ;

section       = section-header, {section-content} ;
section-header = "[", section-name, "]", newline ;
section-content = indent, (node | edge | group | style | flow-step), newline ;

node          = identifier, ":", label, {"|", property} ;
edge          = identifier, edge-op, identifier, [":", label], {"|", property} ;
edge-op       = "->" | "-->" | ".." | "<->" | "<-->" ;

property      = property-name, [":", property-value] ;
label         = simple-string | quoted-string ;
simple-string = {printable - special} ;
quoted-string = '"', {any-char}, '"' ;

12. References

• Quick Reference

• Token Efficiency Analysis

• Extension Authoring Guide